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

  • [アーティクル]

適用対象: 2023-07-01-Preview、2021-04-30-Preview、2020-06-30-Preview

重要

2023-07-01-Preview (変更なし)。

2021-04-30-Preview では、他の Azure リソースへのインデクサー接続に対するマネージド ID のサポートが追加されます。

  • 検索サービスがマネージド ID で実行され、Azure ロールの割り当てによってデータへの読み取りアクセスが許可されている場合、"資格情報" は値として Azure リソース ID を受け入れます。
  • "identity" は 、ユーザー割り当てマネージド ID を受け入れます。 このプロパティは、データ接続の第 1 レベルです。 また、Azure Key Vault でカスタマー マネージド キーを取得するための "encryptionKey" の下にあります。
  • Azure Filesサポートはプレビュー段階です。 プレビュー API を使用して、このデータ ソースからインデックスを作成します。

2020-06-30-Preview は次を追加します。

  • "dataDeletionDetectionPolicy" は 、BLOB インデクサーの "NativeBlobSoftDeleteDeletionDetectionPolicy" を受け入れます。
  • Azure Database for MySQLサポートはプレビュー段階です。 プレビュー API を使用して、このデータ ソースからインデックスを作成します。
  • Cosmos DB MongoDB API と Gremlin API のサポートはプレビュー段階です。 プレビュー API を使用して、このデータ ソースからインデックスを作成します。

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 はすべてのサービス要求に必要です。 オブジェクトが存在しない場合は、作成されます。 既に存在する場合は、新しい定義を使用して上書きされます。

注意

データ ソースが存在する場合、更新要求で type プロパティを変更することはできません。 代わりに、必要な型を使用して新しいデータ ソースを作成する必要があります。

URI パラメーター

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

要求ヘッダー

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

フィールド 説明
Content-Type 必須。 これを application/json
api-key Azure ロールを使用していて、要求にベアラー トークンが指定されている場合は省略可能。それ以外の場合はキーが必要です。 api-key は、検索サービスに対する要求を認証する一意のシステム生成文字列です。 要求の作成には、(クエリ キーではなく) 管理キーに設定されたヘッダーを含める 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" : (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)"}
      }
}

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

プロパティ 説明
name 必須。 データ ソースの名前です。 データ ソース名には、小文字、数字、またはダッシュのみを含める必要があり、ダッシュで開始または終了することはできません。128 文字に制限されています。
description 任意の説明です。
type 必須。 サポートされているデータ ソースの種類
adlsgen2
azureblob
のいずれかである必要があります。Azure Cosmos DB 用の Azure File Storage for Azure SQL
azurefiles Database
azuretable for Azure Table Storage

azuresqlcosmosdb のAzure Blob StorageのAzure Data Lake Storage Gen2の場合SQL API、MongoDB API、Gremlin API
mysql for Azure Database for MySQL
credentials 必須。 接続方法を connectionString 指定する プロパティを含みます。
container 必須。 インデックスを作成するデータを含むコンテナー、コレクション、テーブル、またはビューを指定します。
dataChangeDetectionPolicy 省略可能。 変更されたデータ項目を識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。
dataDeletionDetectionPolicy 省略可能。 データ プラットフォームがデータを削除する方法を識別します。
encryptionKey 省略可能。 Azure Key Vault のカスタマー マネージド暗号化キー (CMK) を使用したデータ ソース資格情報の追加暗号化に使用されます。 2019-01-01 以降に作成された課金対象の検索サービスで使用できます。
disabled 省略可能。 インデクサーが無効な状態で作成されるかどうかを示すブール値。これにより、インデクサーがすぐに実行できなくなります。 既定では false です。
identity 省略可能。 型の #Microsoft.Azure.Search.DataUserAssignedIdentity がuserAssignedIdentity含まれており、外部リソースのユーザー割り当てマネージド ID を指定します。 このプロパティは、各データ ソースの種類のマネージド ID 接続に適切な形式 (リソース ID) の接続文字列があることによって異なりますcredentials。

プロパティが identity null の場合、リソース ID への接続はシステム管理プロパティを使用して行われます。

このプロパティが 型 #Microsoft.Azure.Search.DataNoneIdentityに割り当てられている場合は、以前に指定した明示的な ID がクリアされます。

Response

要求成功の場合: 新しいデータ ソースが作成された場合は「201 作成されました」で、既存のデータ ソースが更新された場合は「204 コンテンツがありません」。

例

例: 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 統合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 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"
        }
    }
}

定義

Link 説明
container インデックスを作成するデータを含むコンテナー、コレクション、テーブル、またはビューを指定します。
credentials インデクサーが connectionString Azure リソースに接続する方法を指定するプロパティが含まれています。
dataChangeDetectionPolicy 変更されたデータを識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。
dataDeletionDetectionPolicy 削除されたデータを検出するメカニズムを指定します。
encryptionKey カスタマー マネージド暗号化のために Azure Key Vault への接続を構成します。

container

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

属性 説明
name 必須。 Azure Cosmos DB の場合は、SQL API コレクションを指定します。 Azure Blob Storageの場合は、ストレージ コンテナーを指定します。 Azure SQLの場合は、テーブルまたはビューを指定します。 [dbo].[mytable]などのスキーマ修飾名を使用できます。 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では、クエリはサポートされていません (代わりにビューを使用してください)。

資格情報

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

属性 説明
connectionString 必須。 インデクサー データ ソースへの接続を指定します。 データ ソース定義を更新する場合、接続文字列は必要ありません。 値<unchanged>または <redacted> は、実際の接続文字列の代わりに使用できます。

キーまたはサインイン資格情報を使用して認証された接続の場合、これらの値は接続文字列に表示されます。 接続文字列の形式は、データ ソースの種類によって異なります。

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 ポータルにあります。

マネージド ID を使用して認証する場合は、接続の資格情報を省略できます。

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

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

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

dataChangeDetectionPolicy

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

属性 説明
dataChangeDetectionPolicy 省略可能。 有効なポリシーには、 または がSqlIntegratedChangeDetectionPolicy含まれますHighWatermarkChangeDetectionPolicy。

HighWatermarkChangeDetectionPolicy は、他の更新プログラムと連携して更新される既存の列またはプロパティに依存します (すべての挿入によって透かし列が更新されます)、値の変更が大きくなります。

SqlIntegratedChangeDetectionPolicyは、SQL Serverのネイティブ変更検出機能を参照するために使用されます。 このポリシーはテーブルでのみ使用できます。ビューでは使用できません。 このポリシーを使用する前に、使用しているテーブルの変更追跡を有効にする必要があります。 指示については、「変更の追跡の有効化と無効化」をご覧ください。
highWaterMarkColumnName HighWatermarkChangeDetectionPolicy の場合は必須。 Cosmos DB の場合、列は プロパティである _ts 必要があります。 Azure SQLの場合は、インデックス付きrowversion列をお勧めします。 Azure Storage の場合、変更検出は lastModified 値を使用して組み込まれているため、dataChangeDetectionPolicy を設定する必要はありません。

dataDeletionDetectionPolicy

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

属性 説明
dataDeletionDetectionPolicy 省略可能。 有効な値は または SoftDeleteColumnDeletionDetectionPolicyNativeBlobSoftDeleteDeletionDetectionPolicy です ( 「ネイティブ BLOB の論理的な削除 (プレビュー)」を参照してください)。

現在、一般公開されているポリシーはSoftDeleteColumnDeletionDetectionPolicy、データ ソース内の "論理的な削除" 列またはプロパティの値に基づいて削除済みアイテムを識別するポリシーのみです。

softDeleteColumnName" 必須。 行の削除状態を指定する値を提供するデータ ソース内の列の名前。 たとえば、"IsDeleted" という名前の列を作成できます。 文字列、整数、またはブール値を持つ列のみがサポートされます。
softDeleteMarkerValue 必須。 論理的な削除列の値。 softDeleteMarkerValue として使用される値は、それに対応する列に整数またはブール値が含まれているとしても、文字列にする必要があります。 たとえば、データ ソースに表示される値が 1 の場合は、 として "1" を使用します softDeleteMarkerValue。 インデクサーは、論理的な削除列からこの値を読み取ると、対応する検索ドキュメントを検索インデックスから削除します。

encryptionKey

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

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

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

属性 説明
keyVaultKeyName 必須。 暗号化に使用される Azure Key Vault キーの名前。
keyVaultKeyVersion 必須。 Azure Key Vault キーのバージョン。
keyVaultUri 必須。 キーを提供する Azure Key Vault (DNS 名とも呼ばれます) の URI。 URI の例として、https://my-keyvault-name.vault.azure.net があります。
accessCredentials マネージド ID を使用している場合は省略します。 それ以外の場合、 のaccessCredentialsプロパティには 、(指定した Azure Key Vaultへのアクセス許可を持つ Azure Active Directory アプリケーション ID)、および applicationSecret (指定した Azure AD アプリケーションの認証キー) が含まれますapplicationId。
identity Azure Key Vault への検索サービス接続にユーザー割り当てマネージド ID を使用している場合を除き、省略可能です。 形式は "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]" です。

こちらもご覧ください