Vytvoření zdroje dat (rozhraní REST API služby Azure AI Search)

Článek
02/28/2024

Ve službě Azure AI Search se zdroj dat používá s indexery, které poskytují informace o připojení pro aktualizaci na vyžádání nebo plánovanou aktualizaci dat cílového indexu a načítá data z podporovaných zdrojů dat Azure.

Na žádost můžete použít post nebo PUT. U obou z nich dokument JSON v textu požadavku poskytuje definici objektu.

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

Případně můžete použít PUT a zadat název v identifikátoru 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 se vyžaduje pro všechny žádosti o služby. Pokud objekt neexistuje, vytvoří se. Pokud už existuje, aktualizuje se na novou definici.

Poznámka

Maximální počet indexů, které můžete vytvořit, se liší podle cenové úrovně. Další informace najdete v tématu Limity služby.

Parametry identifikátoru URI

Parametr	Popis
název služby	Povinná hodnota. Nastavte ho na jedinečný, uživatelem definovaný název vaší vyhledávací služby.
název zdroje dat	Vyžaduje se u identifikátoru URI, pokud používáte PUT. Název musí být malé, musí začínat písmenem nebo číslicí, nesmí obsahovat lomítka ani tečky a musí být kratší než 128 znaků. Název musí začínat písmenem nebo číslicí, ale zbytek názvu může obsahovat jakékoli písmeno, číslice a pomlčky, pokud pomlčky nejsou po sobě jdoucí.
verze-api	Povinná hodnota. Seznam podporovaných verzí najdete v tématu Verze rozhraní API .

Hlavičky požadavku

Následující tabulka popisuje požadovanou a volitelnou hlavičku požadavku.

Pole	Description
Typ obsahu	Povinná hodnota. Nastavte tuto možnost na `application/json`
klíč rozhraní API	Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Požadavky na vytvoření musí obsahovat hlavičku nastavenou `api-key` na klíč správce (na rozdíl od klíče dotazu). Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Text požadavku

Tělo požadavku obsahuje definici zdroje dat, která zahrnuje typ zdroje dat, přihlašovací údaje pro čtení dat a volitelné zásady detekce změn dat a odstranění dat, které se používají k efektivní identifikaci změněných nebo odstraněných dat ve zdroji dat při použití s pravidelně naplánovaným indexerem.

Následující kód JSON představuje základní reprezentaci hlavních částí definice.

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

Požadavek obsahuje následující vlastnosti:

Vlastnost	Popis
name	Povinná hodnota. Název zdroje dat. Název zdroje dat musí obsahovat pouze malá písmena, číslice nebo pomlčky, nesmí začínat ani končit pomlčkami a je omezený na 128 znaků.
description	Volitelný popis.
typ	Povinná hodnota. Musí to být jeden z podporovaných typů zdrojů dat: `azuresql` pro Azure SQL Database , Azure SQL Managed Instance nebo SQL Server instance běžící na virtuálním `cosmosdb` počítači Azure pro Azure Cosmos DB for NoSQL, Azure Cosmos DB pro MongoDB (Preview) nebo Azure Cosmos DB pro Apache Gremlin (Preview). `azureblob` pro Azure Blob Storage `adlsgen2` pro Azure Data Lake Storage Gen2 `azuretable` pro Azure Table Storage `azurefile` pro Azure Files (Preview) `mysql` pro Azure Database for MySQL ( preview) `sharepoint` pro SharePoint v Microsoftu 365 (Preview)
Přihlašovací údaje	Povinná hodnota. Obsahuje `connectionString` vlastnost, která určuje připojovací řetězec pro zdroj dat. Formát připojovací řetězec závisí na typu zdroje dat: U Azure SQL Database se jedná o obvyklý SQL Server připojovací řetězec. Pokud k načtení připojovací řetězec používáte Azure Portal, zvolte možnost `ADO.NET connection string` . V případě služby Azure Cosmos DB musí být připojovací řetězec v následujícím formátu: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Všechny hodnoty jsou povinné. Najdete je v Azure Portal. Pro Azure Blob Storage jsou formáty připojovací řetězec definované v části Přihlašovací údaje v tématu Konfigurace indexování objektů blob ve službě Azure AI Search. Azure Storage, Azure SQL Database a Azure Cosmos DB také podporují připojovací řetězec spravované identity, která v připojovací řetězec neobsahuje klíč účtu. Pokud chcete použít formát spravované identity připojovací řetězec, postupujte podle pokynů k nastavení připojení indexeru ke zdroji dat pomocí spravované identity. Pokud aktualizujete zdroj dat, připojovací řetězec se nevyžaduje. Místo skutečného připojovací řetězec lze použít hodnoty `<unchanged>` nebo `<redacted>` .
kontejner	Povinná hodnota. Určuje data, která se mají indexovat, pomocí `name` vlastností `name` (povinné) a `query` (volitelné): Pro Azure SQL určuje tabulku nebo zobrazení. Můžete použít názvy kvalifikované schématem, například `[dbo].[mytable]`. Pro Službu Azure Cosmos DB určuje kolekci rozhraní SQL API. Pro Azure Blob Storage určuje kontejner úložiště. Pro Azure Table Storage určuje název tabulky. `query`: V případě služby Azure Cosmos DB umožňuje zadat dotaz, který zploštědí libovolné rozložení dokumentu JSON do plochého schématu, které může služba Azure AI Search indexovat. Pro Azure Blob Storage umožňuje zadat virtuální složku v rámci kontejneru objektů blob. Například pro cestu k `mycontainer/documents/blob.pdfdocuments` objektu blob je možné použít jako virtuální složku. Pro Azure Table Storage umožňuje zadat dotaz, který filtruje sadu řádků, které se mají importovat. U Azure SQL se dotaz nepodporuje. Místo toho použijte zobrazení.
dataChangeDetectionPolicy	Nepovinný parametr. Používá se k identifikaci změněné položky dat. Podporované zásady se liší v závislosti na typu zdroje dat. Platné zásady jsou zásady detekce změn s vysokou meze a zásady integrované detekce změn SQL. Zásada detekce velkých změn vodoznaku závisí na existujícím sloupci nebo vlastnosti, která se aktualizuje společně s dalšími aktualizacemi (všechna vložení vedou k aktualizaci sloupce vodoznaku), a změna hodnoty je vyšší. Pro zdroje dat Cosmos DB musíte použít `_ts` vlastnost . Pro Azure SQL je indexovaný `rowversion` sloupec ideálním kandidátem pro použití s politikou horní meze. Ve službě Azure Storage je detekce změn integrovaná s použitím hodnot lastModified, takže není potřeba nastavovat zásady dataChangeDetectionPolicy pro úložiště objektů blob nebo tabulek. Zásady integrovaného zjišťování změn SQL slouží k odkazování na nativní funkce detekce změn v SQL Server. Tuto zásadu lze použít pouze s tabulkami. Nejde ho použít se zobrazeními. Abyste mohli tuto zásadu použít, musíte pro tabulku, kterou používáte, povolit sledování změn. Pokyny najdete v tématu Povolení a zakázání sledování změn . Další informace o podpoře detekce změn v indexeru najdete v tématu Připojení k obsahu a indexování Azure SQL obsahu.
dataDeletionDetectionPolicy	Nepovinný parametr. Používá se k identifikaci odstraněných položek dat. V současné době jsou jedinou podporovanou zásadou obnovitelného odstranění, která identifikuje odstraněné položky na základě hodnoty sloupce nebo vlastnosti obnovitelného odstranění ve zdroji dat. Podporují se pouze sloupce s řetězcovými, celočíselnými nebo logickými hodnotami. Hodnota použitá jako `softDeleteMarkerValue` musí být řetězec, a to i v případě, že odpovídající sloupec obsahuje celá čísla nebo logické hodnoty. Pokud je například ve zdroji dat zobrazená hodnota 1, použijte jako `softDeleteMarkerValue`hodnotu 1 .
šifrovací klíč	Nepovinný parametr. Slouží k šifrování neaktivního neaktivního zdroje dat pomocí vlastních klíčů spravovaných v Azure Key Vault. K dispozici pro fakturovatelné vyhledávací služby vytvořené 1. 1. 2019 nebo později. Oddíl `encryptionKey` obsahuje uživatelem definovaný `keyVaultKeyName` (povinné), systémově vygenerovaný `keyVaultKeyVersion` (povinné) a `keyVaultUri` zadaný klíč (povinný, označovaný také jako název DNS). Příkladem identifikátoru URI může být "https://my-keyvault-name.vault.azure.net". Volitelně můžete určit `accessCredentials` , jestli nepoužíváte identitu spravovaného systému. `accessCredentials` Vlastnosti zahrnují `applicationId` (Microsoft Entra ID ID aplikace, kterému byla udělena přístupová oprávnění k zadanému Key Vault Azure) a `applicationSecret` (ověřovací klíč registrované aplikace). Příklad v další části znázorňuje syntaxi.

Odpověď

Pro úspěšný požadavek: 201 Vytvořeno.

Příklady

Příklad: Azure SQL s detekcí změn (zásady detekce změn s vysokým využitím vodoznaku)

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

Příklad: Azure SQL s detekcí změn (zásady integrovaného Change Tracking 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" }
}

Příklad: Azure SQL s detekcí změn s detekcí odstranění

Vzpomeňte si, že vlastnosti pro detekci odstranění jsou softDeleteColumnName a 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" }  
}

Příklad: Zdroj dat pouze s požadovanými vlastnostmi

Volitelné vlastnosti související s detekcí změn a odstranění můžete vynechat, pokud chcete zdroj dat použít pouze pro jednorázovou kopii dat:

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

Příklad: Vynechání přihlašovacích údajů

Pokud máte v úmyslu aktualizovat zdroj dat, přihlašovací údaje se nevyžadují. Hodnoty <unchanged> nebo <redacted> lze použít místo připojovací řetězec.

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

Příklad: Šifrovací klíče

Šifrovací klíče jsou klíče spravované zákazníkem, které slouží k dodatečnému šifrování. Další informace najdete v tématu Šifrování pomocí klíčů spravovaných zákazníkem v 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)"}
      }
}