次の方法で共有

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

  • [アーティクル]

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

大事な

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

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

  • "資格情報" は、検索サービスがマネージド ID で実行され、Azure ロールの割り当てによってデータへの読み取りアクセスが許可されている場合に、Azure リソース ID を値として受け入れます。
  • "id" は、ユーザー割り当てマネージド 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 パラメーター

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

要求ヘッダー

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

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

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

財産 形容
名前 必須。 データ ソースの名前。 データ ソース名には、小文字、数字、またはダッシュのみを含める必要があり、ダッシュで始めたり終わったりすることはできません。128 文字に制限されています。
形容 省略可能な説明。
種類 必須。 サポートされるデータ ソースの種類の 1 つである必要があります。Azure Cosmos DB SQL API用の Azure Table Storage を するための Azure Sql Database 用の Azure File Storage を するための Azure Blob Storage を するための MongoDB API、Gremlin API for Azure Database for MySQL
資格情報 を する 必須。 接続方法を指定する connectionString プロパティが含まれています。
コンテナ 必須。 インデックスを作成するデータを含むコンテナー、コレクション、テーブル、またはビューを指定します。
dataChangeDetectionPolicy の 随意。 変更されたデータ項目を識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。
dataDeletionDetectionPolicy を する 随意。 データ プラットフォームがデータを削除する方法を識別します。
encryptionKey 随意。 Azure Key Vault カスタマー マネージド暗号化キー (CMK) を使用して、データ ソース資格情報の追加の暗号化に使用されます。 2019-01-01 以降に作成された課金対象の検索サービスで使用できます。
無効 随意。 インデクサーが無効な状態で作成されるかどうかを示すブール値。これにより、インデクサーがすぐに実行されなくなります。 既定では False です。
同一性 随意。 #Microsoft.Azure.Search.DataUserAssignedIdentity 型の userAssignedIdentity が含まれており、外部リソースの ユーザー割り当てマネージド ID を指定します。 このプロパティは、各データ ソースの種類のマネージド ID 接続に適切な形式 (リソース ID) の接続文字列を持つ credentials に依存します。

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

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

応答

要求が成功した場合: 新しいデータ ソースが作成された場合は 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 プロパティが含まれています。
dataChangeDetectionPolicy の 変更されたデータを識別するためのデータ プラットフォームによって提供されるメカニズムを指定します。
dataDeletionDetectionPolicy を する 削除されたデータを検出するためのメカニズムを指定します。
encryptionKey カスタマー マネージド暗号化用に Azure Key Vault への接続を構成します。

コンテナ

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

属性 形容
名前 必須。 Azure Cosmos DB の場合は、SQL API コレクションを指定します。 Azure Blob Storage の場合は、ストレージ コンテナーを指定します。 Azure SQL の場合は、テーブルまたはビューを指定します。 [dbo].[mytable]など、スキーマ修飾名を使用できます。 Azure Table Storage の場合は、テーブルの名前を指定します。
クエリ 随意。 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 portalで見つけることができます。

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

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

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

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

dataChangeDetectionPolicy

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

属性 形容
dataChangeDetectionPolicy 随意。 有効なポリシーには、HighWatermarkChangeDetectionPolicy または SqlIntegratedChangeDetectionPolicyが含まれます。

HighWatermarkChangeDetectionPolicy は、他の更新プログラムと並行して更新される既存の列またはプロパティに依存します (すべての挿入によってウォーターマーク列が更新されます)。値の変更は高くなります。

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

dataDeletionDetectionPolicy

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

属性 形容
dataDeletionDetectionPolicy 随意。 有効な値は または です (ネイティブ BLOB の論理的な削除 (プレビュー)参照)。

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

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

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

関連項目