Tous les produits
Search
Centre de documentation

OpenSearch:Tutoriels

Dernière mise à jour :Aug 20, 2026

Ce tutoriel vous guide pas à pas dans l'intégration d'OpenSearch à une application PHP à l'aide du SDK OpenSearch pour PHP. À la fin, vous aurez envoyé des documents vers une application OpenSearch et exécuté votre première requête de recherche.

Remarque

Ce tutoriel présente une intégration minimale fonctionnelle utilisant le SDK PHP. Pour les déploiements en production, consultez la documentation de référence du SDK ainsi que le guide de configuration du schéma d'application.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Un compte Alibaba Cloud avec une application OpenSearch créée et configurée (champs d'index, champs d'attribut, sources de données et conditions de filtrage)

  • Le SDK OpenSearch pour PHP (V3), téléchargé depuis la rubrique Téléchargements et ajouté à votre projet

  • Un utilisateur Resource Access Management (RAM) disposant des autorisations requises attribuées au rôle AliyunServiceRoleForOpenSearch. Consultez les rubriques AliyunServiceRoleForOpenSearch et Règles d'autorisation d'accès.

Remarque

Pour configurer rapidement le schéma de votre application, téléchargez le modèle de schéma d'application. Dans la console OpenSearch, accédez à la page Configure Application, cliquez sur Import Template et importez le fichier. Ce modèle est compatible avec le code de démonstration présenté dans ce tutoriel.

Étape 1 : Configurer les identifiants

Stockez vos identifiants AccessKey sous forme de variables d'environnement. Ne codez jamais les identifiants en dur dans les fichiers source.

Important

Utilisez un utilisateur RAM plutôt que les identifiants racine de votre compte Alibaba Cloud. Consultez les rubriques Créer un utilisateur RAM et Créer une paire de clés AccessKey.

Linux et macOS

Remplacez <access_key_id> et <access_key_secret> par l'AccessKey ID et l'AccessKey Secret de votre utilisateur RAM.

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

Windows

  1. Créez un fichier de variables d'environnement et ajoutez ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET avec leurs valeurs respectives.

  2. Redémarrez Windows pour que les modifications prennent effet.

Étape 2 : Définir la configuration de base

Créez un fichier Config.inc.php partagé par tous les autres composants de votre intégration. Il initialise le client OpenSearch avec vos identifiants, votre endpoint et le nom de votre application.

<?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);

Remplacez <region endPoint>, <app name> et <suggest name> par les valeurs obtenues depuis la console OpenSearch.

Étape 3 : Importer les fichiers d'en-tête et créer les clients

Le SDK OpenSearch pour PHP utilise des clients spécifiques à chaque fonctionnalité. Importez les fichiers d'en-tête correspondant aux fonctionnalités nécessaires, puis instanciez les objets clients associés.

Fichiers d'en-tête

<?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;

Objets clients

<?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);

Le tableau suivant récapitule les quatre clients et leurs rôles :

Client Classe Objectif
$appClient AppClient Interroger les informations de l'application
$searchClient SearchClient Exécuter des requêtes de recherche
$documentClient DocumentClient Envoyer des documents
$suggestClient SuggestClient Récupérer des suggestions de saisie semi-automatique

Étape 4 : Envoyer des documents

Les documents envoyés à OpenSearch doivent être des chaînes JSON. Chaque document est un objet comportant deux champs :

Champ Description
cmd Opération à effectuer. Valeurs valides : ADD, DELETE, UPDATE. Pour les applications standard, seules les opérations ADD et DELETE sont prises en charge ; pour mettre à jour un document, utilisez ADD et fournissez tous les champs.
fields Paires clé-valeur définissant le contenu du document (par exemple, title, body, url).
Remarque

Pour tester avec des exemples de données, accédez à la page Instance Management dans la console OpenSearch, cliquez sur More > Upload File dans la colonne Actions et téléchargez l'exemple de fichier depuis la boîte de dialogue Upload File.

L'exemple suivant envoie 10 documents à l'aide de l'opération 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 envoi réussi renvoie une réponse HTTP 200. Si $ret->traceInfo->tracer contient des détails d'erreur, consultez l'Étape 6 : Déboguer les requêtes.

Étape 5 : Exécuter une requête de recherche

Utilisez SearchClient et SearchParamsBuilder pour construire et exécuter une requête.

<?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 le résultat est vide ou inattendu, vérifiez votre mot-clé de requête ainsi que la configuration des champs d'index.

Étape 6 : Déboguer les requêtes

Lorsqu'une requête renvoie des résultats inattendus ou qu'une opération échoue, affichez les informations de trace pour obtenir tous les détails de la requête et de la réponse :

echo $ret->traceInfo->tracer;

Lorsque vous soumettez un problème au support technique d'OpenSearch via TradeManager ou le groupe de support DingTalk, incluez la sortie complète de tracer.

Étapes suivantes

  • Explorer l'API complète : Consultez la documentation de référence du SDK pour connaître tous les paramètres de requête disponibles, y compris les conditions de filtrage, les requêtes d'agrégation et le classement personnalisé.

  • Activer les suggestions de saisie semi-automatique : Utilisez SuggestClient et SuggestParamsBuilder avec le $suggestName configuré dans Config.inc.php.