Tous les produits
Search
Centre de documentation

OpenSearch:Exemple de code pour implémenter les requêtes de défilement

Dernière mise à jour :Aug 10, 2026

Utilisez les requêtes de défilement pour récupérer par lots de grands jeux de résultats depuis OpenSearch Industry Algorithm Edition. Chaque requête renvoie un identifiant de défilement (scroll_id) à transmettre à la requête suivante, ce qui permet de parcourir tous les documents correspondants sans omettre ni dupliquer de résultats.

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

Configurer les variables d'environnement

Stockez vos identifiants dans des variables d'environnement plutôt que de les coder en dur dans votre code source.

Important

Utilisez un utilisateur Resource Access Management (RAM) pour appeler les opérations d'API au lieu de votre compte racine Alibaba Cloud. La paire de clés AccessKey du compte racine offre un accès à toutes les opérations d'API, ce qui présente un risque inutile. Pour créer un utilisateur RAM et générer une paire de clés AccessKey, consultez les rubriques Créer un utilisateur RAM et Créer une paire de clés AccessKey. Nous vous déconseillons d'inclure votre paire de clés AccessKey dans des supports facilement accessibles à des tiers, tels que le code du projet. Dans le cas contraire, vos clés pourraient être divulguées et les ressources de votre compte deviendraient vulnérables.

Linux et macOS

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

Remplacez <access_key_id> et <access_key_secret> par l'ID de clé AccessKey et la clé secrète AccessKey de votre utilisateur RAM.

Windows

  1. Créez un fichier de variables d'environnement et ajoutez les variables ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET en leur attribuant respectivement votre ID de clé AccessKey et votre clé secrète AccessKey.

  2. Redémarrez Windows pour prendre en compte les modifications.

Créer le fichier de configuration

Créez un fichier d'en-tête (Config.inc.php) qui initialise le client OpenSearch. Tous les scripts de requêtes de défilement importent ce fichier.

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

// Read credentials from environment variables.
// Set these variables before running the code. See "Set up environment variables".
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

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

// The name of your OpenSearch application.
$appName = '<app name>';

// The name of your drop-down suggestion model.
$suggestName = '<suggest name>';

// Enable debug mode to log request and response details.
$options = array('debug' => true);

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

Remplacez les espaces réservés suivants :

Espace réservé Description
<region endPoint> Le point de terminaison d'API de votre région. Vous le trouverez sur la page des détails de l'application dans la console OpenSearch.
<app name> Le nom de votre application OpenSearch.
<suggest name> Le nom de votre modèle de suggestions déroulantes.

Exécuter des requêtes de défilement

Le processus complet d'une requête de défilement comporte deux étapes :

  • Étape 1 : Démarrer le défilement — Soumettez la requête initiale avec un délai d'expiration pour le défilement. La réponse inclut un scroll_id et initialise le contexte de défilement. Utilisez la valeur viewtotal de cette réponse pour déterminer le nombre de lots suivants à récupérer.

  • Étape 2 : Récupérer les lots — Transmettez le scroll_id issu de la réponse précédente pour récupérer le lot de résultats suivant. Répétez l'opération jusqu'à la récupération de tous les documents correspondants.

Dans le SDK OpenSearch pour PHP V3, les requêtes de défilement ne prennent en charge le tri que sur un seul champ, qui doit être de type INT. Triez par clé primaire pour éviter les doublons ou les omissions de résultats lorsque les données sont mises à jour pendant le défilement.

Le code suivant implémente une boucle complète de requête de défilement :

<?php
header("Content-Type:text/html;charset=utf-8");

// Import the configuration file created in the previous step.
require_once("Config.inc.php");
use OpenSearch\Client\SearchClient;
use OpenSearch\Util\SearchParamsBuilder;

$searchClient = new SearchClient($client);

// Build the initial query parameters.
$params = new SearchParamsBuilder();

// Number of documents to return per scroll batch. No offset is required.
$params->setHits(1);

// The name of your OpenSearch application.
$params->setAppName('The application name');

// The search query.
$params->setQuery("name: 'Search'");

// Response format. Supported values: JSON, FULLJSON.
$params->setFormat("fulljson");

// Sort by the primary key (INT type, ascending).
// Sorting by the primary key prevents duplicate results when data is updated during the scroll.
$params->addSort('id', SearchParamsBuilder::SORT_INCREASE);

// Filter condition.
$params->setFilter('id>0');

// Fields to include in the response.
$params->setFetchFields(array('id', 'name', 'phone', 'int_arr', 'literal_arr', 'float_arr', 'cate_id'));

// Stage 1: Submit the initial query.
// Set the scroll expiry to 3 minutes. The first query does not require a scroll ID.
// The response returns a scroll_id for subsequent queries and viewtotal (total matching documents).
$params->setScrollExpire('3m');
$ret = $searchClient->execute($params->build())->result;

// Stage 2: Retrieve subsequent batches using the scroll ID from each previous response.
// viewtotal is the total number of matching documents returned by the initial query.
for ($i = 0; $i < json_decode($ret)->result->viewtotal; $i++) {
    // Pass the scroll ID from the previous response.
    $params->setScrollId(json_decode($ret)->result->scroll_id);

    // Fetch the next batch.
    $ret = $searchClient->execute($params->build())->result;

    // Display the results.
    print_r($ret . '<br/><br/>');
}

Paramètres clés

Paramètre Méthode Valeur dans l'exemple Description
Taille du lot setHits() 1 Nombre de documents par lot. Aucun décalage (offset) n'est nécessaire.
Requête de recherche setQuery() "name: 'Search'" Expression de la requête de recherche.
Format de réponse setFormat() "fulljson" Format de la réponse. Valeurs prises en charge : JSON, FULLJSON.
Champ de tri addSort() 'id', SORT_INCREASE Doit être un unique champ de type INT. Utilisez la clé primaire pour éviter les doublons.
Filtre setFilter() 'id>0' Expression de filtre appliquée à la requête.
Champs à récupérer setFetchFields() array('id', 'name', ...) Champs à renvoyer dans chaque document.
Expiration du défilement setScrollExpire() '3m' Période de validité de l'identifiant de défilement (scroll_id) pour la prochaine requête de défilement, exprimée en minutes.

Étapes suivantes