データ ソースの作成または更新 (プレビュー REST API)

: 2023-07-01-Preview に適用されます。 このバージョンはサポートされなくなりました。 新しいバージョンにすぐに アップグレードします。

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

作成要求で POST または PUT を使用できます。 どちらの場合も、要求本文はオブジェクト定義を提供します。

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 パラメーター

要求ヘッダー

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

要求本文

要求の本文には、データ ソース定義が含まれています。これには、データ ソースの種類、データを読み取る資格情報、および定期的にスケジュールされたインデクサーで使用される場合にデータ ソース内の変更または削除されたデータを効率的に識別するために使用されるオプションのデータ変更検出およびデータ削除検出ポリシーが含まれます。

次の 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" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "identity": (optional) {Sets the Resource ID of a managed identity. See below for details },
    "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.",
      "identity": "(Resource ID of a user-assigned managed identity, used for connecting to key vault)",
      "accessCredentials": (Credentials for connecting to key vault. Omit if using a managed identity) {
        "applicationId": "Azure AD Application ID that has access permissions to the key vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
} 

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

応答

要求が成功した場合: 新しいデータ ソースが作成された場合は 201 が作成され、既存のデータ ソースが更新された場合は 204 No Content。

例

例: Azure ロールとシステム割り当てマネージド ID

検索サービスにシステム割り当てマネージド ID とロールの割り当てがある場合、データ ソース接続にはストレージ アカウントの一意のリソース ID を指定できます。

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
  }

例: Azure ロールとユーザー割り当てマネージド ID (プレビュー)

この例では、ユーザー割り当てマネージド ID を持つ検索サービスの Azure AD 認証接続を示します。

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]"
    }
  }

例: 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 統合変更追跡ポリシー)

{   
    "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 identity) {
        "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

例: ユーザー割り当てマネージド ID を持つ検索サービスによる暗号化キー コンテナー接続

この例では、accessCredentials を省略します。 ユーザー割り当てマネージド ID 割り当てられているリソースの場合は、encryptionKey で ID を指定し、その ID と Azure ロールの割り当てを使用してキーを取得できます。

{
    "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",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-identity"
        }
    }
}

定義

コンテナ

インデックスを作成するデータを含むコンテナー、コレクション、テーブル、またはビューを指定します。

資格 情報

インデクサーが Azure リソースに接続する方法を指定する "connectionString" プロパティが含まれています。

マネージド ID を使用して認証される接続の場合、接続文字列は Azure リソース ID を指定します (接続文字列形式については、Azure Storage、Cosmos DB、SQL Database) を参照してください)。

外部データ ソースをスコープとしたロールの割り当てによって、インデクサーが接続できるかどうかが決まります。また、Azure Active Directory で信頼できるサービスとして実行されるように検索サービスを構成する必要があります。

"id" プロパティも指定されている場合、"id" プロパティによって提供される検索サービスのユーザー割り当てマネージド ID を使用して接続が確立されます。 それ以外の場合、"identity" が指定されていないか null の場合、接続はシステム マネージド ID を介して行われます。

dataChangeDetectionPolicy

変更されたデータを識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。 サポートされるポリシーは、データ ソースの種類によって異なります。

dataDeletionDetectionPolicy

削除されたデータを識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。 サポートされるポリシーは、データ ソースの種類によって異なります。

encryptionKey

カスタマー マネージド暗号化キー (CMK)の補足 Azure Key Vault への接続を構成します。 カスタマー マネージド キーを使用した暗号化は、無料サービスでは利用できません。 課金対象サービスの場合、2019-01-01 以降に作成された検索サービスでのみ使用できます。

キー コンテナーへの接続を認証する必要があります。 この目的には、"accessCredentials" またはマネージド ID を使用できます。

マネージド ID は、システムまたはユーザー割り当て (プレビュー) にすることができます。 検索サービスにシステム割り当てマネージド ID と、キー コンテナーへの読み取りアクセスを許可するロールの割り当ての両方がある場合は、"identity" と "accessCredentials" の両方を省略でき、要求はマネージド ID を使用して認証されます。 検索サービスにユーザー割り当て ID とロールの割り当てがある場合は、"identity" プロパティをその ID のリソース ID に設定します。

関連項目

• インデクサーの概要
• インデクサー の作成
• カスタマー マネージド暗号化 の