OpenSearch:チュートリアル

前提条件

開始前に、以下の要件を満たしていることを確認してください。

• OpenSearch アプリケーションが作成・構成済み（インデックスフィールド、属性フィールド、データソース、フィルター条件）の Alibaba Cloud アカウント (root ユーザー)

• ダウンロード トピックから取得した OpenSearch SDK for PHP (V3) がプロジェクトに追加されていること

• 必要な権限が AliyunServiceRoleForOpenSearch ロールに付与された Resource Access Management (RAM) ユーザー。 「AliyunServiceRoleForOpenSearch」および「アクセス権限付与ルール」を参照してください。

ステップ 1：認証情報の構成

AccessKey 認証情報を環境変数として保存します。ソースファイル内に認証情報をハードコードしないでください。

Linux および macOS

<access_key_id> および <access_key_secret> をご利用の RAM ユーザーの AccessKey ID および AccessKey Secret に置き換えます。

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

Windows

1. 環境変数ファイルを作成し、ALIBABA_CLOUD_ACCESS_KEY_ID および ALIBABA_CLOUD_ACCESS_KEY_SECRET をそれぞれの値とともに追加します。

2. 変更を有効にするために Windows を再起動します。

ステップ 2：基本構成の設定

統合の他のすべての部分で共有する Config.inc.php ファイルを作成します。このファイルは、認証情報、エンドポイント、アプリケーション名を使用して OpenSearch クライアントを初期化します。

<?php
// オートローダーをインポートします。
require_once("../OpenSearch/Autoloader/Autoloader.php");
use OpenSearch\Client\OpenSearchClient;

// 環境変数から認証情報を読み取ります。
$accessKeyId = getenv('ALIBABA_CLOUD_ACCESS_KEY_ID');
$secret      = getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET');

// リージョンの API エンドポイントを設定します。
// この値は、OpenSearch コンソールのアプリケーション詳細ページで確認できます。
$endPoint    = '<region endPoint>';

// アプリケーション名および検索候補名を設定します。
$appName     = '<app name>';
$suggestName = '<suggest name>';

// トレース情報を取得するためにデバッグモードを有効にします。
$options = array('debug' => true);

// OpenSearch クライアントを作成します。
$client = new OpenSearchClient($accessKeyId, $secret, $endPoint, $options);

<region endPoint>、<app name>、および <suggest name> を OpenSearch コンソールの値に置き換えます。

ステップ 3：ヘッダーファイルのインポートとクライアントの作成

OpenSearch SDK for PHP は機能ごとに専用のクライアントを使用します。必要な機能のヘッダーファイルをインポートし、対応するクライアントオブジェクトをインスタンス化します。

ヘッダーファイル

<?php
// 基本構成（すべての機能で必須）。
require_once("../OpenSearch/Autoloader/Autoloader.php");
use OpenSearch\Client\OpenSearchClient;

// アプリケーション情報の照会。
require_once("Config.inc.php");
use OpenSearch\Client\AppClient;
use OpenSearch\Generated\Common\Pageable;

// ドキュメントの照会（検索）。
require_once("Config.inc.php");
use OpenSearch\Client\SearchClient;
use OpenSearch\Util\SearchParamsBuilder;

// ドキュメントのプッシュ。
require_once("Config.inc.php");
use OpenSearch\Client\DocumentClient;

// 検索候補。
require_once("Config.inc.php");
use OpenSearch\Client\SuggestClient;
use OpenSearch\Util\SuggestParamsBuilder;

クライアントオブジェクト

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

// アプリケーション情報照会クライアント。
$appClient = new AppClient($client);

// ドキュメント照会（検索）クライアント。
$searchClient = new SearchClient($client);

// ドキュメントプッシュクライアント。
$documentClient = new DocumentClient($client);

// 検索候補クライアント。
$suggestClient = new SuggestClient($client);

次の表は、4 つのクライアントとその役割をまとめたものです。

ステップ 4：ドキュメントのプッシュ

OpenSearch にプッシュされるドキュメントは JSON 文字列である必要があります。各ドキュメントは、次の 2 つのフィールドを持つオブジェクトです。

次の例では、ADD 操作を使用して 10 件のドキュメントをプッシュします。

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

// ドキュメントをプッシュするテーブルを指定します。
$tableName = '<table name>';

$documentClient = new DocumentClient($client);

// ドキュメント配列を構築します。
$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;
}

// エンコードしてプッシュします。
$json = json_encode($docs_to_upload);
$ret  = $documentClient->push($json, $appName, $tableName);

プッシュが成功すると、HTTP 200 応答が返されます。$ret->traceInfo->tracer にエラーの詳細が含まれる場合は、「ステップ 6：リクエストのデバッグ」をご参照ください。

ステップ 5：検索クエリの実行

SearchClient および SearchParamsBuilder を使用してクエリを構築・実行します。

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

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

// config 句のパラメーター。
$params->setStart(0);     // 結果の開始オフセット。
$params->setHits(20);     // 返される結果の件数。

// クエリパラメーター。
$params->setAppName('<app name>');
$params->setQuery("name: 'Search'");
$params->setFormat('fulljson');

// 関連スコアの降順で並べ替えます。
$params->addSort('RANK', SearchParamsBuilder::SORT_DECREASE);

// 実行してデコードします。
$ret    = $searchClient->execute($params->build());
$result = json_decode($ret->result, true);
print_r($result);

結果が空または予期しないものである場合は、クエリキーワードおよびインデックスフィールドの構成を確認してください。

ステップ 6：リクエストのデバッグ

クエリが予期しない結果を返す場合や操作が失敗した場合は、トレース情報を出力してリクエストおよび応答の詳細を取得します。

echo $ret->traceInfo->tracer;

TradeManager または DingTalk サポートグループを通じて OpenSearch テクニカルサポートに問題をエスカレーションする際は、完全な tracer 出力を含めてください。

次のステップ

• API 全体の探索：フィルター条件、集計クエリ、カスタムランキングなど、利用可能なすべてのクエリパラメーターについては、SDK リファレンスドキュメントをご参照ください。

• 検索候補の有効化：SuggestClient および SuggestParamsBuilder を、Config.inc.php で構成された $suggestName とともに使用します。