データソースの作成 (Azure AI Search REST API)

[アーティクル]
10/06/2023

Azure AI Search では、インデクサーと共にデータソースが使用され、ターゲットインデックスのオンデマンドまたはスケジュールされたデータ更新の接続情報が提供され、サポートされている Azure データソースからデータがプルされます。

要求に対して POST または PUT を使用できます。どちらの場合も、要求本文の JSON ドキュメントによってオブジェクト定義が提供されます。

POST https://[service name].search.windows.net/datasources?api-version=[api-version]  
    Content-Type: application/json  
    api-key: [admin key]

または、PUT を使用して URI に名前を指定することもできます。

PUT https://[service name].search.windows.net/datasources/[data source name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

HTTPS はすべてのサービス要求に必要です。オブジェクトが存在しない場合は、作成されます。既に存在する場合は、新しい定義に更新されます。

注意

作成できるインデックスの最大数は、料金階層によって異なります。詳細については、サービスの制限に関する記事を参照してください。

URI パラメーター

パラメーター	説明
サービス名	必須。これを検索サービスの一意のユーザー定義名に設定します。
データソース名 (data source name)	PUT を使用する場合は、URI で必須です。名前は小文字で、文字または数字で始まり、スラッシュやドットがなく、128 文字未満である必要があります。名前は文字または数字で始まる必要がありますが、ダッシュが連続していない限り、名前の残りの部分には任意の文字、数字、ダッシュを含めることができます。
api-version	必須。サポートされているバージョンの一覧については、「API のバージョン」を参照してください。

要求ヘッダー

次の表では、必須と省略可能の要求ヘッダーについて説明します。

フィールド説明

Content-Type 必須。これを application/json

api-key Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。要求の作成には、(クエリキーではなく) 管理者キーに設定されたヘッダーを含める api-key 必要があります。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

フィールド	説明
Content-Type	必須。これを `application/json`
api-key	Azure ロールを使用していて、要求でベアラートークンが提供されている場合は省略可能。それ以外の場合はキーが必要です。要求の作成には、(クエリキーではなく) 管理者キーに設定されたヘッダーを含める `api-key` 必要があります。詳細については、「キー認証を使用して Azure AI Search に接続する」を参照してください。

要求本文

要求本文にはデータソースの定義が含まれます。この定義には、データソースの種類、データを読むための資格情報、定期的にスケジュールされたインデクサーで使用するときに、データソースで変更または削除されたデータを効率的に識別するための任意のデータ変更検出/データ削除検出ポリシーが含まれます。

次の JSON は、定義のメイン部分の大まかな表現です。

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },
    "container": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

要求には次のプロパティが含まれます。

プロパティ	説明
name	必須。データソースの名前です。データソース名には小文字、数字、またはダッシュのみを含める必要があり、ダッシュで開始または終了することはできません。128 文字に制限されています。
description	任意の説明です。
type	必須。サポートされているデータソースの種類の 1 つである必要があります。Azure SQL Azure Cosmos DB for NoSQL、Azure Cosmos DB for MongoDB (プレビュー) または Azure Cosmos DB for Apache Gremlin (プレビュー) `azureblob` 用の Azure VM `cosmosdb` で実行されているAzure SQL Managed InstanceまたはSQL Server インスタンスの場合は、サポートされているデータソースの種類 `azuresql`のいずれかです。for Azure Blob Storage `adlsgen2` for Azure Data Lake Storage Gen2 `azuretable` for Azure Table Storage `azurefile` for Azure Files (プレビュー) `mysql` for Azure Database for MySQL ( `sharepoint`Microsoft 365 の SharePoint のプレビュー (プレビュー)
資格情報	必須。これには、データソースの`connectionString`接続文字列を指定するプロパティが含まれています。接続文字列の形式は、データソースの種類によって異なります。 Azure SQL Database の場合、これは通常のSQL Server 接続文字列です。 Azure portalを使用して接続文字列を取得する場合は、オプションを選択します`ADO.NET connection string`。 Azure Cosmos DB の場合、接続文字列の形式はである必要があります。 `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"` すべての値が必須です。値は Azure ポータルにあります。 Azure Blob Storageの場合、接続文字列形式は、「Azure AI Search で BLOB インデックス作成を構成する方法」の「資格情報」セクションで定義されています。 Azure Storage、Azure SQL Database、および Azure Cosmos DB では、接続文字列にアカウントキーを含まないマネージド ID 接続文字列もサポートされています。マネージド ID 接続文字列形式を使用するには、「マネージド ID を使用してデータソースへのインデクサー接続を設定する」の手順に従います。データソースを更新する場合、接続文字列は必要ありません。値`<unchanged>`または `<redacted>` は、実際の接続文字列の代わりに使用できます。
container	必須。 (必須) プロパティと (省略可能) プロパティを`name`使用してインデックスを作成するデータを指定します。 `name` Azure SQLの場合は、テーブルまたはビューを指定します。`query` `[dbo].[mytable]`などのスキーマ修飾名を使用できます。 Azure Cosmos DB の場合は、SQL API コレクションを指定します。 Azure Blob Storageの場合は、ストレージコンテナーを指定します。 Azure Table Storage の場合は、テーブルの名前を指定します。 `query`: Azure Cosmos DB の場合、では、任意の JSON ドキュメントレイアウトを、Azure AI Search でインデックスを作成できるフラットスキーマにフラット化するクエリを指定できます。 Azure Blob Storageでは、BLOB コンテナー内の仮想フォルダーを指定できます。たとえば、BLOB パス `mycontainer/documents/blob.pdf` については、`documents` を仮想フォルダーとして使用できます。 Azure Table Storage では、インポートする行のセットをフィルター処理するクエリを指定できます。 Azure SQLの場合、クエリはサポートされていません。代わりにビューを使用してください。
dataChangeDetectionPolicy	省略可能。変更されたデータ項目を識別するために使用されます。サポートされているポリシーは、データソースの種類によって異なります。有効なポリシーは、高基準値変更検出ポリシーと SQL 統合変更検出ポリシーです。高基準値の変更検出ポリシーは、他の更新プログラムと共に更新される既存の列またはプロパティに依存します (すべての挿入によって透かし列が更新されます)、値の変更が大きくなります。 Cosmos DB データソースの場合は、プロパティを使用する `_ts` 必要があります。 Azure SQLの場合、インデックス付き`rowversion`列は、高基準値ポリシーでの使用に最適な候補です。 Azure Storage の場合、変更検出は lastModified 値を使用して組み込まれているため、BLOB またはテーブルストレージの dataChangeDetectionPolicy を設定する必要はありません。 SQL 統合変更検出ポリシーは、SQL Serverのネイティブ変更検出機能を参照するために使用されます。このポリシーはテーブルでのみ使用できます。ビューでは使用できません。このポリシーを使用する前に、使用しているテーブルの変更追跡を有効にする必要があります。指示については、「変更の追跡の有効化と無効化」をご覧ください。インデクサーでの変更検出のサポートの詳細については、「コンテンツに接続してインデックスを作成する」Azure SQL参照してください。
dataDeletionDetectionPolicy	省略可能。削除されたデータ項目を識別するために使用されます。現在サポートされているポリシーは論理的な削除ポリシーのみです。これは、データソース内の "論理的な削除" 列またはプロパティの値に基づいて削除済みアイテムを識別します。文字列、整数、またはブール値を持つ列のみがサポートされています。 `softDeleteMarkerValue` として使用される値は、それに対応する列に整数またはブール値が含まれているとしても、文字列にする必要があります。たとえば、データソースに表示される値が 1 の場合は、として "1" を使用します `softDeleteMarkerValue`。
encryptionKey	省略可能。 Azure Key Vaultで管理されている独自のキーを使用して保存データソースを暗号化するために使用されます。 2019-01-01 以降に作成された課金対象の検索サービスで使用できます。 `encryptionKey`セクションには、ユーザー定義 `keyVaultKeyName` (必須)、システムによって生成された `keyVaultKeyVersion` (必須)、および`keyVaultUri`キーを指定する (必須、DNS 名とも呼ばれます) が含まれます。 URI の例としては、"https://my-keyvault-name.vault.azure.net"" があります。必要に応じて、マネージドシステム ID を使用していないかどうかを指定 `accessCredentials` できます。の`accessCredentials`プロパティには、(Microsoft Entra ID指定した Azure Key Vaultへのアクセス許可が付与されたアプリケーション ID)、および `applicationSecret` (登録済みアプリケーションの認証キー) が含`applicationId`まれます。次のセクションの例は、構文を示しています。

Response

要求成功の場合: 201 作成されました。

例

例: 変更検出を使用したAzure SQL (高基準値の変更検出ポリシー)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}

例: 変更検出を使用したAzure SQL (SQL 統合Change Tracking ポリシー)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}

例: 削除検出を使用した変更検出を使用したAzure SQL

削除検出のプロパティは softDeleteColumnName とであることを思い出してください softDeleteMarkerValue。

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}

例: 必須プロパティのみを含むデータソース

変更と削除の検出に関連する省略可能なプロパティは、データの 1 回限りのコピーにのみデータソースを使用する場合は省略できます。

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}

例: 資格情報の省略

データソースを更新する場合、資格情報は必要ありません。値<unchanged>または <redacted> は、接続文字列の代わりに使用できます。

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

例: 暗号化キー

暗号化キーは、追加の暗号化に使用されるカスタマーマネージドキーです。詳細については、「Azure Key Vault でのカスタマーマネージドキーを使用した暗号化」を参照してください。

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

データソースの作成 (Azure AI Search REST API)

URI パラメーター

要求ヘッダー

要求本文

Response

例

関連項目

その他のリソース

データ ソースの作成 (Azure AI Search REST API)

URI パラメーター

要求ヘッダー

要求本文

Response

例

関連項目

その他のリソース

データソースの作成 (Azure AI Search REST API)