建立 Azure AI 搜尋服務 REST API (數據源)

發行項
03/05/2024

在 Azure AI 搜尋服務中，數據源會與索引器搭配使用，提供目標索引的隨選或排程數據重新整理連線資訊，從支援的 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 參數

參數	Description
服務名稱	必要。將此設定為搜尋服務的唯一用戶定義名稱。
資料來源名稱 (data source name)	如果使用 PUT，則為 URI 的必要專案。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。名稱的開頭必須是字母或數位，但名稱的其餘部分可以包含任何字母、數位和虛線，只要虛線不是連續的。
api-version	必要。如需支援的版本清單，請參閱 API 版本。

要求標頭

下表說明必要及選用的要求標頭。

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，而且要求會提供持有人令牌，則為選擇性，否則需要密鑰。建立要求必須包含 `api-key` 設定為系統管理員密鑰的標頭 (，而不是查詢密鑰) 。如需詳細資訊，請參閱使用密鑰驗證連線到 Azure AI 搜尋服務。

要求本文

要求的本文包含資料來源定義，該定義包括資料來源類型、資料讀取認證，以及選用的資料變更偵測和資料刪除偵測原則，以在搭配定期排程的索引子時，可有效識別資料來源中經變更或刪除的資料。

下列 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) { }
}

要求可包含下列屬性：

屬性	Description
NAME	必要。資料來源的名稱。數據源名稱只能包含小寫字母、數位或破折號，不能以破折號開頭或結尾，且限制為128個字元。
description	選擇性的描述。
類型	必要。必須是其中一種支持的數據源類型： `azuresql` 適用於 Azure SQL Database、Azure SQL 受控執行個體或 SQL Server 實例，適用於 NoSQL 的 Azure Cosmos DB、適用於 MongoDB 的 Azure `cosmosdb`Cosmos DB (預覽) 或適用於 Apache Gremlin 的 Azure Cosmos DB (預覽版) `azureblob` `azuretableadlsgen2`Azure 檔案儲存體 (預覽 `mysql` 版的 Azure 資料表記憶體 `azurefile` Azure Data Lake Storage Gen2 Azure Blob 儲存體) 適用於 MySQL 的 Azure 資料庫 (預覽版) `sharepoint`for SharePoint in Microsoft 365 (preview)
認證	必要。它包含屬性`connectionString`，指定數據源的連接字串。連接字串的格式取決於數據源類型：針對 Azure SQL Database，這是一般 SQL Server 連接字串。如果您使用 Azure 入口網站來擷取連接字串，請選擇 `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 儲存體，連接字串格式定義於如何在 Azure AI 搜尋中設定 Blob 索引的認證一節中。 Azure 記憶體、Azure SQL 資料庫和 Azure Cosmos DB 也支援受控識別連接字串，該受控識別不會在連接字串中包含帳戶密鑰。若要使用受控識別連接字串格式，請遵循使用受控識別設定數據源索引器連線的指示。如果您要更新數據源，則不需要連接字串。值`<unchanged>`或 `<redacted>` 可用來取代實際連接字串。
容器	必要。指定要使用`name`必要 () 和 `query` (選擇性) 屬性來編製索引的數據：： `name` 針對 Azure SQL，指定數據表或檢視表。您可以使用符合結構描述的名稱，例如 `[dbo].[mytable]`。針對 Azure Cosmos DB，指定 SQL API 集合。針對 Azure Blob 儲存體，指定記憶體容器。針對 Azure 資料表記憶體，指定資料表的名稱。 `query`：針對 Azure Cosmos DB，可讓您指定查詢，將任意 JSON 檔配置扁平化為 Azure AI 搜尋可編制索引的一般架構。針對 Azure Blob 儲存體，可讓您在 Blob 容器內指定虛擬資料夾。例如，就 Blob 路徑 `mycontainer/documents/blob.pdf` 而言，`documents` 可用來作為虛擬資料夾。針對 Azure 資料表記憶體，可讓您指定查詢，以篩選要匯入的數據列集。對於 Azure SQL，不支持查詢。請改用檢視。
dataChangeDetectionPolicy	選擇性。用來識別已變更的數據項。支援的原則根據資料來源類型而有所不同。有效原則為高水位線變更偵測原則和 SQL 整合式變更偵測原則。高水印變更偵測原則取決於與其他更新一起更新的現有數據行或屬性， (所有插入都會造成浮浮水印數據行) 的更新，且值變更較高。針對 Cosmos DB 數據源，您必須使用 `_ts` 屬性。對於 Azure SQL，索引`rowversion`數據行是搭配高水位標記原則使用的理想候選專案。針對 Azure 記憶體，變更偵測是使用 lastModified 值內建的，不需要為 Blob 或數據表記憶體設定 dataChangeDetectionPolicy。 SQL 整合式變更偵測原則可用來參考 SQL Server 中的原生變更偵測功能。此原則只能與數據表搭配使用;它不能與檢視搭配使用。您必須先啟用正在使用之資料表的變更追蹤，才能使用這項原則。如需指示，請參閱啟用和停用變更追蹤。如需索引器中變更偵測支援的詳細資訊，請參閱連線至和索引 Azure SQL 內容。
dataDeletionDetectionPolicy	選擇性。用來識別已刪除的數據項。目前唯一支持的原則是虛刪除原則，它會根據數據源中 'soft delete' 資料行或屬性的值來識別已刪除的專案。僅支援具有字串、整數或布爾值的數據行。即使對應的資料行具有整數或布林值，做為 `softDeleteMarkerValue` 的值仍必須是字串。例如，如果資料來源中顯示的值為 1，請使用「1」作為 `softDeleteMarkerValue`。
encryptionKey	選擇性。用來使用您自己的金鑰加密待用數據源，並在 Azure 金鑰保存庫中管理。可用於在 2019-01-01 之後建立的可計費搜尋服務。區 `encryptionKey` 段包含使用者定義的 `keyVaultKeyName` (必要) 、系統產生的 `keyVaultKeyVersion` (必要) ，以及 `keyVaultUri` 提供所需的密鑰 (，也稱為 DNS 名稱) 。範例 URI 可能是 “https://my-keyvault-name.vault.azure.net"。您可以選擇性地指定 `accessCredentials` 您是否未使用受控系統識別。 `accessCredentials`的屬性包括 `applicationId` (Microsoft Entra ID 應用程式識別碼，這些標識碼已授與您指定 Azure 金鑰保存庫) 的訪問許可權，以及 `applicationSecret` (已註冊應用程式) 的驗證密鑰。下一節中的範例說明語法。

回應

要求成功：「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 整合式 (變更追蹤原則) 變更偵測

{   
    "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" }  
}

範例：僅具有必要屬性的數據源

如果您只想要針對資料的一次性復本使用資料源，可以省略與變更和刪除偵測相關的選擇性屬性：

{   
    "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 金鑰保存庫中使用客戶管理的密鑰進行加密。

{
    "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 搜尋服務 REST API (數據源)

URI 參數

要求標頭

要求本文

回應

範例

另請參閱

其他資源