Gegevensbron maken (Azure AI Search REST API)

Artikel
03/05/2024

In Azure AI Search wordt een gegevensbron gebruikt met indexeerfuncties, waarmee de verbindingsgegevens voor on-demand of geplande gegevensvernieuwing van een doelindex worden verstrekt, waarbij gegevens worden opgehaald uit ondersteunde Azure-gegevensbronnen.

U kunt POST of PUT gebruiken voor de aanvraag. Voor beide biedt het JSON-document in de aanvraagbody de objectdefinitie.

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

U kunt ook PUT gebruiken en de naam op de URI opgeven.

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

HTTPS is vereist voor alle serviceaanvragen. Als het object niet bestaat, wordt het gemaakt. Als deze al bestaat, wordt deze bijgewerkt naar de nieuwe definitie.

Notitie

Het maximum aantal indexen dat u kunt maken, verschilt per prijscategorie. Zie Servicelimieten voor meer informatie.

URI-parameters

Parameter	Beschrijving
servicenaam	Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice.
naam van gegevensbron	Vereist voor de URI als u PUT gebruikt. De naam moet kleine letters bevatten, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en minder dan 128 tekens bevatten. De naam moet beginnen met een letter of cijfer, maar de rest van de naam kan een willekeurige letter, cijfer en streepjes bevatten, zolang de streepjes niet opeenvolgend zijn.
api-versie	Vereist. Zie API-versies voor een lijst met ondersteunde versies.

Aanvraagheaders

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Velden	Description
Content-Type	Vereist. Stel dit in op `application/json`
api-key	Optioneel als u Azure-rollen gebruikt en er een Bearer-token is opgegeven voor de aanvraag, anders is een sleutel vereist. Create-aanvragen moeten een `api-key` header bevatten die is ingesteld op uw beheerderssleutel (in plaats van een querysleutel). Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie.

Aanvraagbody

De hoofdtekst van de aanvraag bevat een definitie van de gegevensbron, die het type van de gegevensbron, referenties voor het lezen van de gegevens bevat, evenals een optioneel beleid voor gegevenswijzigingsdetectie en detectie van gegevensverwijdering dat wordt gebruikt om gewijzigde of verwijderde gegevens in de gegevensbron efficiënt te identificeren wanneer deze worden gebruikt met een periodiek geplande indexeerfunctie.

De volgende JSON is een weergave op hoog niveau van de belangrijkste onderdelen van de definitie.

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

Aanvraag bevat de volgende eigenschappen:

Eigenschap	Beschrijving
naam	Vereist. De naam van de gegevensbron. De naam van een gegevensbron mag alleen kleine letters, cijfers of streepjes bevatten, mag niet beginnen of eindigen met streepjes en mag maximaal 128 tekens bevatten.
beschrijving	Een optionele beschrijving.
type	Vereist. Moet een van de ondersteunde gegevensbrontypen zijn: `azuresql` voor Azure SQL Database, Azure SQL Managed Instance of SQL Server exemplaar dat wordt uitgevoerd op Azure VM `cosmosdb` voor Azure Cosmos DB voor NoSQL, Azure Cosmos DB voor MongoDB (preview) of Azure Cosmos DB voor Apache Gremlin (preview) `azureblob` voor Azure Blob Storage `adlsgen2` voor Azure Data Lake Storage Gen2 `azuretable` voor Azure Table Storage `azurefile` voor Azure Files (preview) `mysql` voor Azure Database for MySQL ( preview) `sharepoint` voor SharePoint in Microsoft 365 (preview)
referenties	Vereist. Het bevat een `connectionString` eigenschap die de verbindingsreeks voor de gegevensbron aangeeft. De indeling van de verbindingsreeks is afhankelijk van het gegevensbrontype: voor Azure SQL database is dit de gebruikelijke SQL Server verbindingsreeks. Als u Azure Portal gebruikt om de verbindingsreeks op te halen, kiest u de `ADO.NET connection string` optie. Voor Azure Cosmos DB moet de verbindingsreeks de volgende indeling hebben: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Alle waarden zijn vereist. U vindt ze in de Azure Portal. Voor Azure Blob Storage worden de verbindingsreeks indelingen gedefinieerd in de sectie Referenties van Blob-indexering configureren in Azure AI Search. Azure Storage, Azure SQL Database en Azure Cosmos DB ondersteunen ook een beheerde identiteit verbindingsreeks die geen accountsleutel bevat in de verbindingsreeks. Als u de beheerde identiteit verbindingsreeks-indeling wilt gebruiken, volgt u de instructies voor Het instellen van een indexeerfunctieverbinding met een gegevensbron met behulp van een beheerde identiteit. Als u de gegevensbron bijwerkt, is de verbindingsreeks niet vereist. De waarden `<unchanged>` of `<redacted>` kunnen worden gebruikt in plaats van de werkelijke verbindingsreeks.
container	Vereist. Hiermee geeft u de gegevens te indexeren met behulp van de `name` eigenschappen`name` (vereist) en `query` (optioneel): : voor Azure SQL geeft u de tabel of weergave op. U kunt schema-gekwalificeerde namen gebruiken, zoals `[dbo].[mytable]`. Voor Azure Cosmos DB geeft u de SQL API-verzameling op. Voor Azure Blob Storage geeft u de opslagcontainer op. Voor Azure Table Storage geeft u de naam van de tabel op. `query`: voor Azure Cosmos DB kunt u een query opgeven waarmee een willekeurige JSON-documentindeling wordt afgevlakt in een plat schema dat azure AI Search kan indexeren. Voor Azure Blob Storage kunt u een virtuele map opgeven in de blobcontainer. Voor blobpad `mycontainer/documents/blob.pdfdocuments` kan bijvoorbeeld worden gebruikt als de virtuele map. Voor Azure Table Storage kunt u een query opgeven waarmee de set rijen wordt gefilterd die moeten worden geïmporteerd. Voor Azure SQL wordt query niet ondersteund. Gebruik in plaats daarvan weergaven.
dataChangeDetectionPolicy	Optioneel. Wordt gebruikt om gewijzigde gegevensitems te identificeren. Ondersteunde beleidsregels variëren op basis van het gegevensbrontype. Geldige beleidsregels zijn Beleid voor wijzigingsdetectie met hoog watermerk en GEÏNTEGREERD SQL-beleid voor wijzigingsdetectie. Het detectiebeleid voor hoge watermerken is afhankelijk van een bestaande kolom of eigenschap die wordt bijgewerkt in combinatie met andere updates (alle invoegingen resulteren in een update van de watermerkkolom) en de waardewijziging is hoger. Voor Cosmos DB-gegevensbronnen moet u de `_ts` eigenschap gebruiken. Voor Azure SQL is een geïndexeerde `rowversion` kolom de ideale kandidaat voor gebruik met het beleid voor hoogwatermarkeringen. Voor Azure Storage is wijzigingsdetectie ingebouwd met behulp van lastModified-waarden, waardoor u de dataChangeDetectionPolicy voor blob- of tabelopslag hoeft in te stellen. Sql Integrated Change Detection Policy wordt gebruikt om te verwijzen naar de systeemeigen functies voor wijzigingsdetectie in SQL Server. Dit beleid kan alleen worden gebruikt met tabellen; het kan niet worden gebruikt met weergaven. U moet wijzigingen bijhouden inschakelen voor de tabel die u gebruikt voordat u dit beleid kunt gebruiken. Zie Wijzigingen bijhouden in- en uitschakelen voor instructies. Zie Verbinding maken met en indexeren Azure SQL inhoud voor meer informatie over ondersteuning voor wijzigingsdetectie in de indexeerfunctie.
dataDeletionDetectionPolicy	Optioneel. Wordt gebruikt om verwijderde gegevensitems te identificeren. Momenteel is het enige ondersteunde beleid het beleid voor voorlopig verwijderen, waarmee verwijderde items worden geïdentificeerd op basis van de waarde van een kolom of eigenschap 'voorlopig verwijderen' in de gegevensbron. Alleen kolommen met tekenreeks-, geheel getal- of booleaanse waarden worden ondersteund. De waarde die als `softDeleteMarkerValue` wordt gebruikt, moet een tekenreeks zijn, zelfs als de bijbehorende kolom gehele getallen of booleaanse waarden bevat. Als de waarde die wordt weergegeven in uw gegevensbron bijvoorbeeld 1 is, gebruikt u '1' als de `softDeleteMarkerValue`.
encryptionKey	Optioneel. Wordt gebruikt om de gegevensbron-at-rest te versleutelen met uw eigen sleutels, beheerd in uw Azure Key Vault. Beschikbaar voor factureerbare zoekservices die zijn gemaakt op of na 01-2019. Een `encryptionKey` sectie bevat een door de gebruiker gedefinieerde `keyVaultKeyName` (vereist), een door het systeem gegenereerde `keyVaultKeyVersion` (vereist) en een `keyVaultUri` die de sleutel levert (vereist, ook wel DNS-naam genoemd). Een voorbeeld van een URI kan 'https://my-keyvault-name.vault.azure.net". U kunt desgewenst opgeven `accessCredentials` of u geen beheerde systeemidentiteit gebruikt. Eigenschappen van `accessCredentials` include `applicationId` (Microsoft Entra ID toepassings-id waaraan toegangsmachtigingen zijn verleend voor uw opgegeven Azure Key Vault) en `applicationSecret` (verificatiesleutel van de geregistreerde toepassing). Een voorbeeld in de volgende sectie illustreert de syntaxis.

Antwoord

Voor een geslaagde aanvraag: 201 Gemaakt.

Voorbeelden

Voorbeeld: Azure SQL met wijzigingsdetectie (beleid voor wijzigingsdetectie met hoog watermerk)

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

Voorbeeld: Azure SQL met wijzigingsdetectie (SQL Integrated Wijzigingen bijhouden Policy)

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

Voorbeeld: Azure SQL met wijzigingsdetectie met verwijderingsdetectie

De eigenschappen voor verwijderingsdetectie zijn softDeleteColumnName en 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" }  
}

Voorbeeld: Gegevensbron met alleen vereiste eigenschappen

Optionele eigenschappen met betrekking tot wijzigings- en verwijderingsdetectie kunnen worden weggelaten als u de gegevensbron alleen wilt gebruiken voor een eenmalige kopie van de gegevens:

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

Voorbeeld: Referenties weglaten

Als u de gegevensbron wilt bijwerken, zijn de referenties niet vereist. De waarden <unchanged> of <redacted> kunnen worden gebruikt in plaats van de verbindingsreeks.

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

Voorbeeld: Versleutelingssleutels

Versleutelingssleutels zijn door de klant beheerde sleutels die worden gebruikt voor extra versleuteling. Zie Versleuteling met door de klant beheerde sleutels in Azure Key Vault voor meer informatie.

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

Delen via