Sdílet prostřednictvím

Vytvoření nebo aktualizace zdroje dat (rozhraní REST API verze Preview)

  • Článek

platí pro: 2023-07-01-Preview. Tato verze se už nepodporuje. okamžitě upgradovat na novější verzi.

Důležitý

2023-07-01-Preview (žádné změny).

2021-04-30-Preview přidává podporu spravovaných identit pro připojení indexeru k dalším prostředkům Azure:

  • přihlašovací údaje přijímá ID prostředku Azure jako hodnotu za předpokladu, že vyhledávací služba běží pod spravovanou identitou a přiřazení rolí Azure udělují datům přístup pro čtení.
  • identity přijímá spravovanou identitu přiřazenou uživatelem. Tato vlastnost je první úroveň pro datová připojení. Je také pod "encryptionKey" pro načtení klíče spravovaného zákazníkem ve službě Azure Key Vault.
  • podpora služby Azure Files je ve verzi Preview. K indexování z tohoto zdroje dat použijte rozhraní API ve verzi Preview.

2020-06-30-Preview přidává:

  • "dataDeletionDetectionPolicy" přijímá pro indexery objektů blob "NativeBlobSoftDeleteDeletionDetectionPolicy".
  • podpora služby Azure Database for MySQL je ve verzi Preview. K indexování z tohoto zdroje dat použijte rozhraní API ve verzi Preview.
  • podpora rozhraní MongoDB API služby Cosmos DB a rozhraní Gremlin API je ve verzi Preview. K indexování z tohoto zdroje dat použijte rozhraní API ve verzi Preview.

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

Pro žádost o vytvoření můžete použít post nebo PUT. V každém z nich tělo 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]

Pro žádosti o aktualizace použijte put a zadejte název indexeru na 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]

Pro všechny žádosti o služby se vyžaduje HTTPS. Pokud objekt neexistuje, vytvoří se. Pokud už existuje, přepíše se pomocí nové definice.

Poznámka

Jakmile zdroj dat existuje, nelze u žádosti o aktualizaci změnit vlastnost typu. Místo toho byste měli vytvořit nový zdroj dat s použitím požadovaného typu.

Parametry identifikátoru URI

Parametr Popis
název služby Požadovaný. Nastavte ho na jedinečný uživatelsky definovaný název vyhledávací služby.
název zdroje dat Vyžaduje se u identifikátoru URI, pokud používáte metodu PUT. Název musí obsahovat malá písmena, začínat písmenem nebo číslicí, nesmí obsahovat lomítka ani tečky a musí mít méně než 128 znaků. Po zahájení názvu písmenem nebo číslem může zbytek názvu obsahovat libovolné písmeno, číslo a pomlčky, pokud pomlčky nejsou po sobě jdoucí.
api-version Požadovaný. Další verze najdete v verzích rozhraní API.

Hlavičky požadavku

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

Pole Popis
Typ obsahu Požadovaný. Nastavit na application/json
api-key Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Api-key je jedinečný systémový vygenerovaný řetězec, který ověřuje požadavek ve vaší vyhledávací službě. Žádosti o vytvoření musí obsahovat hlavičku api-key nastavenou na klíč správce (na rozdíl od klíče dotazu). Podrobnosti najdete v tématu Připojení k Azure AI Search pomocí ověřování klíčů.

Text požadavku

Tělo požadavku obsahuje definici zdroje dat, která zahrnuje typ zdroje dat, přihlašovací údaje ke čtení dat, jakož i volitelné zásady detekce změn dat a zásady detekce 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ě plánovaným indexerem.

Následující 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" : (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)"}
      }
}

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

Vlastnost Popis
Jméno Požadovaný. Název zdroje dat. Název zdroje dat musí obsahovat jenom malá písmena, číslice nebo pomlčky, nesmí začínat ani končit pomlčkami a je omezen na 128 znaků.
popis Volitelný popis.
typ Požadovaný. Musí to být jeden z podporovaných typů zdrojů dat: pro azure Data Lake Storage Gen2 pro Azure Blob Storage pro azure File Storage pro azure SQL Database pro Azure Table Storage proazure Cosmos DB SQL API , rozhraní MongoDB API, rozhraní Gremlin API pro Azure Database for MySQL
přihlašovací údaje Požadovaný. Obsahuje vlastnost connectionString, která určuje, jak se připojit.
kontejner Požadovaný. Určuje kontejner, kolekci, tabulku nebo zobrazení obsahující data, která se mají indexovat.
dataChangeDetectionPolicy Volitelný. Určuje mechanismus, který poskytuje datová platforma pro identifikaci změněné datové položky.
dataDeletionDetectionPolicy Volitelný. Určuje, jak datová platforma odstraňuje data.
šifrovacího klíče Volitelný. Používá se k dalšímu šifrování přihlašovacích údajů ke zdroji dat prostřednictvím šifrovacích klíčů spravovaných zákazníkem (CMK) ve službě Azure Key Vault. Dostupné pro fakturovatelné vyhledávací služby vytvořené 1. 1. 2019 nebo po 1. 1. 2019.
invalidní Volitelný. Logická hodnota označující, jestli je indexer vytvořen v zakázaném stavu, což brání jeho okamžitému spuštění. Ve výchozím nastavení je false.
identita Volitelný. Obsahuje userAssignedIdentity typu #Microsoft.Azure.Search.DataUserAssignedIdentity a určuje spravovanou identitu přiřazenou uživatelem externího prostředku. Tato vlastnost závisí na tom, credentials mít připojovací řetězec ve správném formátu (ID prostředku) pro připojení spravovaných identit pro každý typ zdroje dat.

Pokud je vlastnost identity null, připojení k ID prostředku se provádí pomocí vlastnosti spravované systémem.

Pokud je tato vlastnost přiřazena k typu #Microsoft.Azure.Search.DataNoneIdentity, je vymazána jakákoli explicitní identita, která byla zadána dříve.

Odpověď

Pro úspěšnou žádost: 201 Vytvořeno, pokud byl vytvořen nový zdroj dat, a 204 Bez obsahu, pokud byl existující zdroj dat aktualizován.

Příklady

příklad : Role Azure a spravovaná identita přiřazená systémem

Pokud má vyhledávací služba spravovanou identitu přiřazenou systémem a přiřazení role, může být připojení ke zdroji dat jedinečným ID prostředku vašeho účtu úložiště.

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

Příklad : Role Azure a spravovaná identita přiřazená uživatelem (Preview)

Tento příklad ukazuje připojení ověřené službou Azure AD pro vyhledávací službu, která má spravovanou identitu přiřazenou uživatelem.

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

Příklad : Azure SQL s detekcí změn (zásady detekce změn s vysokou mezemi)

{   
    "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 (integrované zásady 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" }
}

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

Vzpomeňte si, že vlastnosti detekce 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 s požadovanými vlastnostmi pouze

Volitelné vlastnosti související s detekcí změn a odstranění je možné vynechat, pokud chcete zdroj dat používat 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 : Použití beze změny nebo redakce možnosti přihlašovacích údajů

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

{
    "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é se používají k dalšímu šifrování. Další informace najdete v tématu Šifrování pomocí klíčů spravovaných zákazníkem ve službě 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)"}
      }
}

příklad : Připojení k trezoru klíčů pomocí vyhledávacích služeb, které mají spravovanou identitu přiřazenou uživatelem,

Tento příklad vynechá accessCredentials. Pro prostředek, který má spravovanou identitu přiřazenou uživatelem, přiřazenou k prostředku, můžete zadat identitu v šifrovacím klíči a načíst klíč pomocí této identity a přiřazení rolí 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"
        }
    }
}

Definice

Propojit Popis
kontejneru Určuje kontejner, kolekci, tabulku nebo zobrazení obsahující data, která se mají indexovat.
přihlašovací údaje Obsahuje vlastnost connectionString, která určuje, jak se indexer připojuje k prostředku Azure.
dataChangeDetectionPolicy Určuje mechanismus, který poskytuje datová platforma pro identifikaci změněná data.
dataDeletionDetectionPolicy Určuje mechanismus pro detekci odstraněných dat.
šifrovacího klíče Nakonfiguruje připojení ke službě Azure Key Vault pro šifrování spravované zákazníkem.

kontejner

Určuje kontejner, kolekci, tabulku nebo zobrazení obsahující data, která se mají indexovat.

Atribut Popis
Jméno Požadovaný. Pro Službu Azure Cosmos DB určuje kolekci rozhraní SQL API. Pro Azure Blob Storage určuje kontejner úložiště. Pro Azure SQL určuje tabulku nebo zobrazení. Můžete použít názvy kvalifikované schématem, například [dbo].[mytable]. Pro Azure Table Storage určuje název tabulky.
dotaz Volitelný. Pro Službu Azure Cosmos DB můžete zadat dotaz, který zploštěje libovolné rozložení dokumentu JSON do plochého schématu, které může Azure AI Search indexovat. Pro Azure Blob Storage umožňuje zadat virtuální složku v kontejneru objektů blob. Například pro cestu k objektu blob mycontainer/documents/blob.pdf, documents lze použít jako virtuální složku. Pro Azure Table Storage můžete zadat dotaz, který filtruje sadu řádků, které se mají importovat. V případě Azure SQL se dotaz nepodporuje (místo toho použijte zobrazení).

pověření

Obsahuje vlastnost connectionString, která určuje, jak se indexer připojuje k prostředku Azure.

Atribut Popis
connectionString Požadovaný. Určuje připojení ke zdroji dat indexeru. Pokud aktualizujete definici zdroje dat, připojovací řetězec se nevyžaduje. Hodnoty <unchanged> nebo <redacted> lze použít místo skutečného připojovacího řetězce.

U připojení, která jsou ověřená pomocí klíčů nebo přihlašovacích údajů, jsou tyto hodnoty viditelné v připojovacím řetězci. Formát připojovacího řetězce závisí na typu zdroje dat:

Pro Azure SQL Database se jedná o obvyklý připojovací řetězec SQL Serveru. Pokud k načtení připojovacího řetězce používáte Azure Portal, zvolte možnost ADO.NET connection string.

pro 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 na webu Azure Portal.

Pokud k ověřenípoužíváte spravovanou identitu , můžete v připojení vynechat přihlašovací údaje.

U připojení, která jsou ověřená pomocí spravované identity, určuje připojovací řetězec ID prostředku Azure (viz tyto odkazy pro formát připojovacího řetězce: Azure Storage, Cosmos DB,SQL Database).

Přiřazení rolí vymezená na externí zdroj dat určují, jestli se indexer může připojit, a vyhledávací služba musí být nakonfigurovaná tak, aby běžela jako důvěryhodná služba v Azure Active Directory.

Pokud je zadána také vlastnost "identity", připojení se provádí pomocí spravované identity přiřazené uživatelem vyhledávací služby poskytnuté vlastností "identita". V opačném případě, pokud je "identita" nezadaná nebo null, je připojení prostřednictvím systémové spravované identity.

dataChangeDetectionPolicy

Určuje mechanismus, který poskytuje datová platforma pro identifikaci změněná data. Podporované zásady se liší v závislosti na typu zdroje dat.

Atribut Popis
dataChangeDetectionPolicy Volitelný. Platné zásady zahrnují HighWatermarkChangeDetectionPolicy nebo SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy závisí na existujícím sloupci nebo vlastnosti, které se aktualizují společně s dalšími aktualizacemi (výsledkem je aktualizace sloupce vodoznaku) a změna hodnoty je vyšší.

SqlIntegratedChangeDetectionPolicy slouží k odkazování na nativní funkce detekce změn na SQL Serveru. 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.
highWaterMarkColumnName Požadováno pro HighWatermarkChangeDetectionPolicy. Ve službě Cosmos DB musí být sloupec _ts vlastnost. Pro Azure SQL se doporučuje indexovaný sloupec rowversion. Pro Azure Storage je detekce změn integrovaná pomocí hodnot lastModified a eliminuje nutnost nastavit dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Určuje mechanismus, který poskytuje datová platforma pro identifikaci odstraněných dat. Podporované zásady se liší v závislosti na typu zdroje dat.

Atribut Popis
dataDeletionDetectionPolicy Volitelný. Platné hodnoty jsou SoftDeleteColumnDeletionDetectionPolicy nebo NativeBlobSoftDeleteDeletionDetectionPolicy (viz nativní obnovitelné odstranění objektů blob (Preview)).

V současné době je jedinou obecně dostupnou zásadouSoftDeleteColumnDeletionDetectionPolicy, která identifikuje odstraněné položky na základě hodnoty sloupce nebo vlastnosti obnovitelného odstranění ve zdroji dat.

softDeleteColumnName" Požadovaný. Název sloupce ve zdroji dat poskytující hodnotu, která určuje stav odstranění řádku. Můžete například vytvořit sloupec s názvem IsDeleted. Podporují se pouze sloupce s řetězcovými, celými čísly nebo logickými hodnotami.
softDeleteMarkerValue Požadovaný. Hodnota sloupce obnovitelného odstranění. Hodnota použitá jako softDeleteMarkerValue musí být řetězec, i když odpovídající sloupec obsahuje celá čísla nebo logické hodnoty. Pokud je například hodnota, která se zobrazí ve zdroji dat 1, použijte jako softDeleteMarkerValue"1". Pokud indexer přečte tuto hodnotu ze sloupce obnovitelného odstranění, odstraní odpovídající vyhledávací dokument z indexu vyhledávání.

encryptionKey

Nakonfiguruje připojení ke službě Azure Key Vault pro doplňkové šifrovacích klíčů spravovaných zákazníkem (CMK). Šifrování pomocí klíčů spravovaných zákazníkem není k dispozici pro bezplatné služby. U fakturovatelných služeb je dostupná jenom pro vyhledávací služby vytvořené 1. 1. 2019 nebo po 1. 1. 2019.

Musí se ověřit připojení k trezoru klíčů. Pro tento účel můžete použít buď accessCredentials, nebo spravovanou identitu.

Spravované identity můžou být systémové nebo uživatelem přiřazené (Preview). Pokud má vyhledávací služba spravovanou identitu přiřazenou systémem i přiřazení role, která uděluje přístup pro čtení k trezoru klíčů, můžete vynechat identitu i accessCredentials a požadavek se ověří pomocí spravované identity. Pokud má vyhledávací služba identitu přiřazenou uživatelem a přiřazení role, nastavte vlastnost identity na ID prostředku této identity.

Atribut Popis
keyVaultKeyName Požadovaný. Název klíče služby Azure Key Vault, který se používá k šifrování.
keyVaultKeyVersion Požadovaný. Verze klíče služby Azure Key Vault
keyVaultUri Požadovaný. Identifikátor URI služby Azure Key Vault (označovaný také jako název DNS), který klíč poskytuje. Příkladem identifikátoru URI může být https://my-keyvault-name.vault.azure.net.
accessCredentials Pokud používáte spravovanou identitu, vynecháte. Jinak vlastnosti accessCredentials zahrnují applicationId (ID aplikace Azure Active Directory, které má přístupová oprávnění k zadané službě Azure Key Vault) a applicationSecret (ověřovací klíč zadané aplikace Azure AD).
identita Volitelné, pokud nepoužíváte spravovanou identitu přiřazenou uživatelem pro připojení vyhledávací služby ke službě Azure Key Vault. Formát je "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Viz také