API の検索とフィルタリング

このページは Apigee と Apigee ハイブリッドに適用されます。

このトピックでは、Vertex AI を搭載したセマンティック検索とフィルタベースの検索オプションを使用して、API Hub で特定のリソースを検索する方法について説明します。

図 1. API Hub には、強力な自然言語検索機能とフィルタ機能が用意されています。

セマンティック検索による API Hub の検索

セマンティック検索を使用すると、API Hub に登録されている API リソースを簡単に検索して表示できます。セマンティック検索では、インスタンスで使用可能なすべての API リソースをフリーテキスト検索クエリによって検索できます。すべてのエンティティ タイプ（API、API オペレーション、仕様など）を検索するか、検索対象のエンティティ タイプを指定できます。

Vertex AI 検索エンジンにより、セマンティック検索は単語の「マッチング」を超えた検索を実現します。詳細な API リソース エントリ内のあらゆる場所から、入力されたフリーテキスト検索クエリと意味的に類似する語句を見つけ出し、その語句が含まれる結果を返します。

フリーテキスト検索では、次のカテゴリの結果が返されます。

• API: 検索に一致する API のリスト。API ごとに、次の詳細が提供されます。
  • API の名前と、API の詳細ページへのリンク。
  • リソースの簡単な説明。
  • リソースのオーナーの名前とメールアドレス。
• バージョン: 検索に一致する API バージョンのリスト。バージョンごとに、次の詳細が表示されます。
  • バージョンに関連付けられている API の名前と、API の詳細ページへのリンク。
  • API バージョンの名前と、バージョンの詳細ページへのリンク。
  • バージョンの説明とそれに関連するメタデータ。
• 仕様: 検索に一致する API 仕様のリスト。仕様ごとに、次の詳細情報が提供されます。
  • 仕様に関連付けられている API の名前と、API の詳細ページへのリンク。
  • API 仕様の名前と、仕様に関連付けられたバージョンの詳細ページへのリンク。
  • 仕様の説明。
  • 仕様ドキュメントへのリンク。
  • OpenAPI 仕様など、仕様のタイプ。
• オペレーション: 検索に一致する API オペレーションのリスト。オペレーションごとに、次の詳細情報が提供されます。
  • オペレーションに関連付けられている API の名前と、API の詳細ページへのリンク。
  • オペレーションの名前と、オペレーションに関連付けられたバージョンの詳細ページへのリンク。
  • 仕様の説明。
  • オペレーションを定義する仕様ドキュメントへのリンク。
  • オペレーションを含むバージョンへのリンク。
• デプロイメント: 検索に一致するデプロイメントのリスト。デプロイメントごとに、次の詳細情報が提供されます。
  • デプロイメントの名前。
  • デプロイメントの説明。
  • デプロイメント タイプ。たとえば、Apigee ハイブリッドなど。
  • デプロイメントを含むバージョンへのリンク。

特定の語句を含む API を検索するには:

1. Google Cloud コンソールで、API Hub の [セマンティック検索] ページに移動します。

   [API Hub] に移動

2. 検索ボックスに検索クエリを入力します。

   たとえば、「Order management APIs」や「Spec file for wireless carrier settings」と入力します。

   検索クエリ プロンプトでシステム属性を使用して、検索を絞り込むことができます。API Hub で API を登録する際にユーザー属性を作成した場合は、その属性を検索クエリのプロンプトに組み込むこともできます。

3. 検索結果は、[API]、[バージョン]、[仕様]、[オペレーション]、[デプロイメント] の各タブに分類されます。いずれかのタブをクリックすると、カテゴリの結果が表示されます。結果には、入力した検索クエリと意味的に類似する語句を含む API リソースが表示されます。
4. API リソース名をクリックすると、リソースの詳細ページが表示されます。
5. 現在のクエリを消去するには、[Clear results] をクリックします。

API による API Hub の検索

API Hub API を使用して API Hub リソースを検索することもできます。searchResources メソッドを使用すると、フリーテキスト クエリとフィルタを使用して API Hub リソースをクエリできます。

次の API 呼び出しを使用して、API Hub リソース全体を検索できます。

curl -X POST https://apihub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"QUERY",
    "filter":"resource_type = RESOURCE_TYPE"
   }'

ここで

• PROJECT_ID は、API Hub インスタンスのホスト プロジェクトの ID です。
• LOCATION は、API Hub インスタンスがホストされている場所です。
• QUERY は、検索で使用するフリーテキスト クエリです。クエリには、表示名、説明、その他のメタデータなど、API Hub リソースの詳細に関連するキーワードを含めることができます。
• RESOURCE_TYPE は、検索に指定するオプションのフィルタです。次のいずれかの API Hub リソースタイプをフィルタとして指定できます。
  • Api
  • ApiOperation
  • Deployment
  • Definition
  • Spec
  • Version

次に例を示します。

curl -X POST https://apihub.googleapis.com/v1/projects/{project-id}/locations/{location}:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"dog status in the store",
    "filter":"resource_type = SPEC"
    }'

この呼び出しでは、リソース固有のメタデータを含む API Hub リソースのリストが複数のページに分かれて返されます。

API Hub API を使用したフリーテキスト検索の詳細については、Method:project.locations.searchResources の API リファレンス ドキュメントをご覧ください。

フィルタベースの検索オプション

システム属性を検索パラメータとして使用して、[API] ページに表示された API のリストを絞り込むことができます。 表示された API リソースのリストをカスタマイズする際は、次の機能を使用します。

• フィルタ
• ページネーション

フィルタ

フィルタベースのリスト検索を使用すると、リソースに関連付けられている事前定義済みのパラメータとシステム属性に基づいて、API のリストを効率化できます。フィルタ適用後のビューは、Match ALL または Match ANY のオプションによってカスタマイズできます。

注: 使用可能なフィルタ オプションは、管理者権限を持つユーザーによって構成されます。詳細については、API Hub の設定を管理する方法と属性を管理する方法をご覧ください。

フィルタ オプションを指定するには:

1. Google Cloud コンソールで、API Hub の [API] ページに移動します。

   API Hub の [API] に移動

2. [表をフィルタ] フィールドをクリックして、表をフィルタします。[フィルタ] ペインが開きます。
   ヒント: API テーブルの列は表示または非表示にできます。[フィルタ] 行のアクション メニューを使用して、行名の選択と選択解除を行います。
3. フィルタ オプションを指定または選択します。[フィルタ] ペインに入力すると、フィルタ オプションのメニューがポップアップ表示されます。このメニューには、現在のコンテキストに関連するシステム属性のリストが含まれています。たとえば、[API] ページで API をフィルタするときに表示されるシステム属性は次のとおりです。
   • API 名: API の表示名
   • ビジネス ユニット: API を担当するビジネス ユニット
   • チーム: API を担当する制作チーム
   • ドキュメント: API ドキュメントのショートリンク。
   注: その他の属性がフィルタ オプションとして表示される場合もあります。詳細については、API 属性を管理する方法をご覧ください。

   システム属性は、[API]、[バージョン]、[仕様] の各テーブルのフィルタリストに表示されます。

4. フィルタ オプションを選択したら、[値] リストからフィルタ値を選択します。また、選択したフィルタ属性の値を入力することもできます。
5. フィルタを追加するには、[表をフィルタ] フィールドをクリックして、使用可能な演算子から演算子を選択し、別のフィルタ属性と値を選択します。

6. 選択したフィルタ プロパティには、フィルタクエリが使用している条件ロジックが表示されます。演算子として OR を選択できます。演算子を選択しないと、デフォルトの AND が使用されます。

7. 個別のフィルタをクリアするには、フィルタの [X] をクリックします。すべてのフィルタをクリアするには、[フィルタ] ペインで [すべてクリア] をクリックします。

ページネーション

API リソースが複数ある場合は、複数のページに分かれて表示されることがあります。

リストの表示をカスタマイズし、ページ間を移動するには:

1. Google Cloud コンソールで、API Hub の [API] ページに移動します。

   API Hub の [API] に移動

   デフォルトでは、[API] リストページが表示されます。

2. [API] リストで、図 2 に示すページネーション ツールを見つけます。

   

   図 2. ページネーションされた結果を前後に移動します。

3. ページごとに表示する API の数を選択します。
4. [> 進む] をクリックして次のページに移動します。
5. [< 戻る] をクリックして前のページに移動します。

次のステップ

• デプロイメントの管理方法を学習する。