REST API を使用して Azure AI Search Serviceを管理する

[アーティクル]
03/20/2024

このアーティクルでは、管理 REST APIを使用して Azure AI Search Serviceを作成および構成する方法について説明します。プレビュー機能への早期アクセスを保証されているのは、Management REST API のみです。

Management REST API は、安定バージョンとプレビューバージョンで使用できます。プレビュー機能にアクセスする場合は、必ずプレビュー API バージョンを設定してください。

サービスを作成または更新する
データプレーンに対する Azure ロールベースのアクセス制御を有効にする
カスタマーマネージドキーポリシーを適用する
セマンティックランク付けを無効にする
外部リソースにデータをプッシュするワークロードを無効にする
クエリキーを作成する
管理者キーを再生成する
プライベートエンドポイント接続を一覧表示する
検索操作を一覧表示する
検索サービスを削除する

すべての Management REST API にはサンプルがあります。この記事で説明されていないタスクについて、API リファレンスを参照してください。

前提条件

Azure サブスクリプション。無料で作成できます。
REST クライアントを使用する Visual Studio Code。
アクセストークンを取得するために使用する Azure CLI。 Azure サブスクリプションの所有者または管理者である必要があります。

アクセストークンを取得する

Management REST API 呼び出しは、Microsoft Entra ID を介して認証されます。要求でアクセストークンと、リソースを作成および構成するためのアクセス許可を提供する必要があります。

Azure CLI または Azure PowerShell を使ってアクセストークンを作成できます。

Azure CLI のコマンドシェルを開きます。
Azure サブスクリプションにサインインします。
```
az login
```
テナント ID とサブスクリプション ID を取得します。複数のテナントまたはサブスクリプションがある場合は、正しいものを使用していることを確認します。
```
az account show
```

アクセストークンを取得します。

az account get-access-token --query accessToken --output tsv

Visual Studio Code を設定する

Visual Studio Code 用の REST クライアントに慣れていない場合、このクイックスタートにはセットアップが含まれているため、タスクを完了することができます。

Visual Studio Code を起動し、[拡張機能] タイルを選択します。
REST クライアントを検索し、[インストール] を選択します。
.rest または .http のファイル拡張子をもつ名前のファイルを開くか、または新規に作成します。

前のステップで取得した値の変数を指定します。

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

サブスクリプションの検索サービスを一覧表示して、セッションが動作可能であることを確認します。

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

[要求の送信] をクリックします。隣接するウィンドウに応答が表示されます。既存の検索サービスがある場合は、一覧表示されます。ない場合、リストは空ですが、HTTP コードが 200 OK である限り、次の手順に進むことができます。

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

サービスを作成または更新する

現在のサブスクリプションで検索サービスを作成または更新します。この例では、まだ定義されていない検索サービス名とリージョンに変数を使用します。名前を直接指定するか、新しい変数をコレクションに追加します。

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

S3HD サービスを作成する

S3HD サービスを作成するには、sku と hostingModeのプロパティと組み合わせを使用します。 sku を standard3 に、"hostingMode" を HighDensity に設定します。

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

データプレーンにロールベースのアクセスを構成する

適用対象: Search インデックスデータ共同作成者、Search インデックスデータ閲覧者、Search サービス共同作成者

この手順では、OAuth2 アクセストークンを提供するデータ要求の承認ヘッダーを認識するように検索サービスを構成します。

データプレーン操作にロールベースのアクセス制御を使用するには、authOptions を aadOrApiKey に設定し、要求を送信します。

ロールベースのアクセス制御を排他的に使用するには、2 番目の要求をフォローアップして API キー認証を無効にします。今回は disableLocalAuth を true に設定します。

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

カスタマーマネージドキーポリシーを適用する

カスタマーマネージド暗号化を使用している場合、検索サービスでコンプライアンスの状態が報告されるようにしたい場合は、"encryptionWithCMK" を有効にすることができます ("enforcement" を "Enabled" に設定します)。

このポリシーを有効にすると、暗号化キーが指定されていない場合に、機密データ (データソース内の接続文字列など) を含むオブジェクトを作成するすべての REST 呼び出しが失敗します: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
            "enforcement": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

セマンティック優先度付けを無効にする

既定ではセマンティック優先度付けは有効になっていませんが、サービスレベルでフィーチャーをロックダウンできます。

### disable semantic ranking
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

外部リソースにデータをプッシュするワークロードを無効にする

Azure AI Searchは、ナレッジストアの更新、デバッグセッションの状態の保存、エンリッチメントのキャッシュ時に外部データソースに書き込みます。次の例では、これらのワークロードをサービスレベルで無効にしています。

### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

検索サービスを削除する

### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

管理者 API キーを一覧表示する

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

管理者 API キーを再生成する

一度に再生成できる管理者 API キーは 1 つだけです。

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer

クエリ API キーを作成する

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

プライベートエンドポイント接続を一覧表示する

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

検索操作を一覧表示する

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

次のステップ

検索サービスを構成したら、次の手順として、ポータル、REST API、または Azure SDK を使用して、インデックスの作成やインデックスのクエリの実行などを行います。