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

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

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

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

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

すべての管理 REST API には例があります。タスクがこの記事で取り上げられていない場合は、代わりに API リファレンスを参照してください。

ヒント

CURL を使用して管理 REST API を呼び出す場合は、コンテンツタイプヘッダーを application/json: -H "Content-Type: application/json"に設定してください。または、JSON を埋め込む場合は、 --JSON フラグを使用することもできます。

前提条件

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

管理 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を開始し、Extensions タイルを選択します。
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 検索機能は、新しいサービスでのみ使用できます。サービスの再作成を回避し、これらの機能を既存のサービスに提供するために、サービスをアップグレードできる場合があります。

### 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 Service 共同作成者

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" を有効にすることができます。

このポリシーを有効にすると、暗号化キーが指定されていない場合、機密データ (データソース内の接続文字列など) を含むオブジェクトを作成する 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"
            }
        }
    }

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

Azure AI 検索ナレッジストアの更新、デバッグセッションの状態の保存、またはエンリッチメントのキャッシュ時に>外部データソースに書き込みます

### 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 ポータル、REST API、またはAzure SDKを使用して、インデックスの作成またはインデックスのクエリが含まれます。

フィードバック

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

Last updated on 2026-05-12