Todos los productos
Search
Centro de documentos

OpenSearch:Tutorials

Última actualización: Sep 04, 2026

Este tutorial le guía paso a paso para integrar OpenSearch en una aplicación PHP mediante el SDK de OpenSearch para PHP. Al finalizar, habrá enviado documentos a una aplicación de OpenSearch y ejecutado su primera consulta de búsqueda.

Nota

Este tutorial aborda una integración funcional mínima con el SDK de PHP. Para despliegues en producción, consulte la documentación de referencia del SDK y la guía de configuración del esquema de la aplicación.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

  • Una cuenta de Alibaba Cloud con una aplicación de OpenSearch creada y configurada (campos de índice, campos de atributos, orígenes de datos y condiciones de filtro).

  • El SDK de OpenSearch para PHP (V3), descargado desde el tema Downloads y agregado a su proyecto.

  • Un usuario de Resource Access Management (RAM) con los permisos obligatorios otorgados al rol AliyunServiceRoleForOpenSearch. Consulte AliyunServiceRoleForOpenSearch y Reglas de autorización de acceso.

Nota

Para configurar rápidamente el esquema de su aplicación, descargue la application schema template. En la consola de OpenSearch, vaya a la página Configure Application, haga clic en Import Template y cargue el archivo. Esta plantilla es compatible con el código de demostración de este tutorial.

Paso 1: Configurar las credenciales

Almacene sus credenciales de AccessKey como variables de entorno. Nunca inserte las credenciales directamente en los archivos de código fuente.

Importante

Utilice un usuario de RAM en lugar de las credenciales raíz de su cuenta de Alibaba Cloud. Consulte Crear un usuario de RAM y Crear un par de AccessKey.

Linux y macOS

Reemplace <access_key_id> y <access_key_secret> con el ID de AccessKey y el secreto de AccessKey de su usuario de RAM.

export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

Windows

  1. Cree un archivo de variables de entorno y agregue ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET con sus valores correspondientes.

  2. Reinicie Windows para que los cambios surtan efecto.

Paso 2: Establecer la configuración base

Cree un archivo Config.inc.php que compartirán todas las demás partes de su integración. Este archivo inicializa el cliente de OpenSearch con sus credenciales, endpoint y nombre de la aplicación.

<?php
// Import the autoloader.
require_once("../OpenSearch/Autoloader/Autoloader.php");
use OpenSearch\Client\OpenSearchClient;

// Read credentials from environment variables.
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret      = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

// Set the API endpoint for your region.
// Find this value on the application details page in the OpenSearch console.
$endPoint    = '<region endPoint>';

// Set the application name and drop-down suggestion name.
$appName     = '<app name>';
$suggestName = '<suggest name>';

// Enable debug mode to capture trace information.
$options = array('debug' => true);

// Create the OpenSearch client.
$client = new OpenSearchClient($accessKeyId, $secret, $endPoint, $options);

Reemplace <region endPoint>, <app name> y <suggest name> con los valores obtenidos en la consola de OpenSearch.

Paso 3: Importar archivos de encabezado y crear clientes

El SDK de OpenSearch para PHP utiliza clientes específicos para cada función. Importe los archivos de encabezado correspondientes a las funciones que necesite y luego cree instancias de los objetos de cliente respectivos.

Archivos de encabezado

<?php
// Base configuration (required for all features).
require_once("../OpenSearch/Autoloader/Autoloader.php");
use OpenSearch\Client\OpenSearchClient;

// Application information query.
require_once("Config.inc.php");
use OpenSearch\Client\AppClient;
use OpenSearch\Generated\Common\Pageable;

// Document query (search).
require_once("Config.inc.php");
use OpenSearch\Client\SearchClient;
use OpenSearch\Util\SearchParamsBuilder;

// Document push.
require_once("Config.inc.php");
use OpenSearch\Client\DocumentClient;

// Drop-down suggestions.
require_once("Config.inc.php");
use OpenSearch\Client\SuggestClient;
use OpenSearch\Util\SuggestParamsBuilder;

Objetos de cliente

<?php
require_once("Config.inc.php");

// Application information query client.
$appClient = new AppClient($client);

// Document query (search) client.
$searchClient = new SearchClient($client);

// Document push client.
$documentClient = new DocumentClient($client);

// Drop-down suggestion client.
$suggestClient = new SuggestClient($client);

La siguiente tabla resume los cuatro clientes y sus propósitos:

Cliente

Clase

Propósito

$appClient

AppClient

Consultar información de la aplicación

$searchClient

SearchClient

Ejecutar consultas de búsqueda

$documentClient

DocumentClient

Enviar documentos

$suggestClient

SuggestClient

Obtener sugerencias desplegables

Paso 4: Enviar documentos

Los documentos enviados a OpenSearch deben ser cadenas JSON. Cada documento es un objeto con dos campos:

Campo

Descripción

cmd

Operación por ejecutar. Valores válidos: ADD, DELETE, UPDATE. Para aplicaciones estándar, solo se admiten ADD y DELETE; para actualizar un documento, utilice ADD y proporcione todos los campos.

fields

Pares clave-valor que definen el contenido del documento (por ejemplo, title, body, url).

Nota

Para realizar pruebas con datos de muestra, vaya a la página Instance Management en la consola de OpenSearch, haga clic en More > Upload File en la columna Actions y descargue el archivo de muestra desde el cuadro de diálogo Upload File.

El siguiente ejemplo envía 10 documentos mediante la operación ADD:

<?php
header("Content-Type:text/html;charset=utf-8");
require_once("Config.inc.php");
use OpenSearch\Client\DocumentClient;

// Specify the table to push documents to.
$tableName = '<table name>';

$documentClient = new DocumentClient($client);

// Build the document array.
$docs_to_upload = array();
for ($i = 0; $i < 10; $i++) {
    $item          = array();
    $item['cmd']   = 'ADD';
    $item['fields'] = array(
        'id'   => $i + 1,
        'name' => 'Search' . $i,
    );
    $docs_to_upload[] = $item;
}

// Encode and push.
$json = json_encode($docs_to_upload);
$ret  = $documentClient->push($json, $appName, $tableName);

Un envío exitoso devuelve una respuesta HTTP 200. Si $ret->traceInfo->tracer contiene detalles de error, consulte el Paso 6: Depurar solicitudes.

Paso 5: Ejecutar una consulta de búsqueda

Utilice SearchClient y SearchParamsBuilder para construir y ejecutar una consulta.

<?php
require_once("Config.inc.php");
use OpenSearch\Client\SearchClient;
use OpenSearch\Util\SearchParamsBuilder;

$searchClient = new SearchClient($client);
$params       = new SearchParamsBuilder();

// config clause parameters.
$params->setStart(0);     // Starting offset of results.
$params->setHits(20);     // Number of results to return.

// Query parameters.
$params->setAppName('<app name>');
$params->setQuery("name: 'Search'");
$params->setFormat('fulljson');

// Sort by relevance score in descending order.
$params->addSort('RANK', SearchParamsBuilder::SORT_DECREASE);

// Execute and decode.
$ret    = $searchClient->execute($params->build());
$result = json_decode($ret->result, true);
print_r($result);

Si el resultado está vacío o no es el esperado, compruebe la palabra clave de consulta y la configuración de los campos de índice.

Paso 6: Depurar solicitudes

Cuando una consulta devuelve resultados inesperados o una operación falla, imprima la información de rastreo para obtener todos los detalles de la solicitud y la respuesta:

echo $ret->traceInfo->tracer;

Al escalar un problema al soporte técnico de OpenSearch a través de TradeManager o el grupo de soporte de DingTalk, incluya la salida completa de tracer.

Pasos siguientes

  • Explore la API completa: Consulte la documentación de referencia del SDK para conocer todos los parámetros de consulta disponibles, incluidas las condiciones de filtro, las consultas agregadas y la clasificación personalizada.

  • Habilite las sugerencias desplegables: Utilice SuggestClient y SuggestParamsBuilder con el valor de $suggestName configurado en Config.inc.php.