REST API を使用して Azure AI Search サービスを管理する

2025-09-30

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

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

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

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

前提条件

アクティブなサブスクリプションを持つ Azure アカウント。無料でアカウントを作成できます。
Visual Studio CodeとREST クライアント。
次の手順で説明するように、アクセストークンを取得する Azure CLI。 Azure サブスクリプションの所有者または管理者である必要があります。

Management REST API 呼び出しは、Microsoft Entra ID を介して認証されます。リソースを作成して構成するには、要求に対するアクセストークンとアクセス許可を指定する必要があります。 Azure CLI に加えて、 Azure PowerShell を使用してアクセストークンを作成できます。
1. Azure CLI のコマンドシェルを開きます。
2. Azure サブスクリプションにサインインします。複数のテナントまたはサブスクリプションがある場合は、正しいテナントまたはサブスクリプションを選択してください。
```
az login
```
3. テナント ID とサブスクリプション ID を取得します。
```
az account show
```
4. アクセストークンを取得します。
```
az account get-access-token --query accessToken --output tsv
```
  テナント ID、サブスクリプション ID、ベアラートークンが必要です。これらの値は、次の手順で作成する .rest または .http ファイルに貼り付けます。

Visual Studio Code を設定する

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

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

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

@tenant-id = PUT-YOUR-TENANT-ID-HERE
@subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
@token = PUT-YOUR-TOKEN-HERE

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

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
      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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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"
        }
      }

サービスをアップグレードする

一部の Azure AI Search 機能は、新しいサービスでのみ使用できます。サービスの再作成を回避し、これらの機能を既存のサービスに提供するために、サービスをアップグレードできる場合があります。

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

価格帯の変更

容量が必要な場合は、別の価格レベルに切り替えることができます。現在、Basic レベルと Standard レベル (S1、S2、S3) のみを切り替えることができます。 sku プロパティを使用して、新しい層を指定します。

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

S3HD サービスを作成する

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

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 に設定します。

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

コンフィデンシャルコンピューティングを構成する

コンフィデンシャルコンピューティングは、使用データ保護用の省略可能なコンピューティングの種類です。構成すると、検索サービスは標準 VM ではなく機密 VM (DCasv5 または DCesv5) にデプロイされます。このコンピューティングの種類では、課金対象レベルに対して 10% の追加料金も発生します。詳細については、価格に関するページを参照してください。

毎日の使用では、コンフィデンシャルコンピューティングは必要ありません。このコンピューティングの種類は、厳しい規制、コンプライアンス、またはセキュリティ要件にのみお勧めします。詳細については、「コンフィデンシャルコンピューティングのユースケース」を参照してください。

コンピューティングの種類は、検索サービスの有効期間中に固定されます。コンフィデンシャルコンピューティングを永続的に構成するには、 computeType プロパティを新しいサービスで confidential するように設定します。

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "___location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

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

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

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

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

セマンティックランカーを無効にする

セマンティックランカーは、無料プランで既定で有効になっており、1 か月あたり最大 1,000 件の要求を無料で許可します。サービスレベルで機能をロックダウンして、使用を防ぐことができます。

### Disable semantic ranker
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

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

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

検索サービスを削除する

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

クエリ API キーを作成する

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

検索操作を一覧表示する

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

次のステップ

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

フィードバック

このページはお役に立ちましたか?