Freigeben über

Erstellen einer Datenquelle (Azure AI Search-REST-API)

  • Artikel

In Azure AI Search wird eine Datenquelle mit Indexern verwendet, die die Verbindungsinformationen für bedarfsgesteuerte oder geplante Datenaktualisierungen eines Zielindexes bereitstellt und Daten aus unterstützten Azure-Datenquellen abruft.

Sie können entweder POST oder PUT für die Anforderung verwenden. Für beides stellt das JSON-Dokument im Anforderungstext die Objektdefinition bereit.

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

Alternativ können Sie PUT verwenden und den Namen für den URI angeben.

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

HTTPS ist für alle Dienstanforderungen erforderlich. Wenn das Objekt nicht vorhanden ist, wird es erstellt. Wenn sie bereits vorhanden ist, wird sie auf die neue Definition aktualisiert.

Hinweis

Die maximale Anzahl von Indizes, die Sie erstellen können, variiert je nach Preisstufe. Weitere Informationen finden Sie unter Diensteinschränkungen.

URI-Parameter

Parameter BESCHREIBUNG
Dienstname Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
Datenquellenname (data source name) Erforderlich für den URI bei Verwendung von PUT. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte aufweisen und weniger als 128 Zeichen umfassen. Der Name muss mit einem Buchstaben oder einer Zahl beginnen, aber der Rest des Namens kann beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgen.
api-version Erforderlich. Eine Liste der unterstützten Versionen finden Sie unter API-Versionen .

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder BESCHREIBUNG
Content-Type Erforderlich. Auf application/json
api-key Optional, wenn Sie Azure-Rollen verwenden und in der Anforderung ein Bearertoken bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Erstellen von Anforderungen muss einen api-key Header enthalten, der auf Ihren Administratorschlüssel festgelegt ist (im Gegensatz zu einem Abfrageschlüssel). Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung .

Anforderungstext

Der Anforderungstext enthält eine Datenquellendefinition, einschließlich Datenquellentyp, Anmeldeinformationen zum Lesen der Daten sowie optionale Richtlinien zur Erkennung von Datenänderungen und Datenlöschungen. Diese Richtlinien werden verwendet, um geänderte und gelöschte Daten in der Datenquelle effizient zu identifizieren, wenn ein regelmäßig geplanter Indexer verwendet wird.

Der folgende JSON-Code ist eine allgemeine Darstellung der Standard Teile der Definition.

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

Die Anforderung enthält die folgenden Eigenschaften:

Eigenschaft BESCHREIBUNG
name Erforderlich. Den Namen der Datenquelle. Ein Datenquellenname darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, darf nicht mit Bindestrichen beginnen oder enden und ist auf 128 Zeichen beschränkt.
description Eine optionale Beschreibung.
type Erforderlich. Muss einer der unterstützten Datenquellentypen sein:

azuresql für Azure SQL-Datenbank, Azure SQL Managed Instance oder SQL Server instance, die auf azure-VM
cosmosdb für Azure Cosmos DB for NoSQL ausgeführt werden, Azure Cosmos DB für MongoDB (Vorschau) oder Azure Cosmos DB für Apache Gremlin (Vorschau)
azureblob für Azure Blob Storage
adlsgen2 für Azure Data Lake Storage Gen2
azuretable für Azure Table Storage
azurefile für Azure Files (Vorschau)
mysql für Azure Database for MySQL (Vorschau)
sharepoint für SharePoint in Microsoft 365(Vorschau)
Anmeldeinformationen Erforderlich. Sie enthält eine connectionString -Eigenschaft, die die Verbindungszeichenfolge für die Datenquelle angibt. Das Format der Verbindungszeichenfolge hängt vom Datenquellentyp ab:

Für Azure SQL-Datenbank ist dies die übliche SQL Server Verbindungszeichenfolge. Wenn Sie Azure-Portal verwenden, um die Verbindungszeichenfolge abzurufen, wählen Sie die ADO.NET connection string Option aus.

Für Azure Cosmos DB muss die Verbindungszeichenfolge das folgende Format aufweisen: "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]". Alle Werte sind erforderlich. Informationen zu den Werten finden Sie im Azure-Portal.

Für Azure Blob Storage werden die Verbindungszeichenfolge Formate im Abschnitt Anmeldeinformationen unter Konfigurieren der Blobindizierung in Azure AI Search definiert.

Azure Storage, Azure SQL Database und Azure Cosmos DB unterstützen auch eine verwaltete Identität Verbindungszeichenfolge, die keinen Kontoschlüssel in der Verbindungszeichenfolge enthält. Um die verwaltete Identität Verbindungszeichenfolge Format zu verwenden, befolgen Sie die Anweisungen unter Einrichten einer Indexerverbindung mit einer Datenquelle mithilfe einer verwalteten Identität.

Wenn Sie die Datenquelle aktualisieren, ist die Verbindungszeichenfolge nicht erforderlich. Die Werte <unchanged> oder <redacted> können anstelle der tatsächlichen Verbindungszeichenfolge verwendet werden.
Container Erforderlich. Gibt die zu indizierenden Daten mit den name Eigenschaften (erforderlich) und query (optional) an:name

:
Gibt für Azure SQL die Tabelle oder Sicht an. Sie können schemaqualifizierte Namen verwenden, z.B. [dbo].[mytable].
Gibt für Azure Cosmos DB die SQL-API-Sammlung an.
Gibt für Azure Blob Storage den Speichercontainer an.
Gibt für Azure Table Storage den Namen der Tabelle an.

query:
Für Azure Cosmos DB können Sie eine Abfrage angeben, die ein beliebiges JSON-Dokumentlayout in ein flaches Schema vereinfacht, das Azure KI Search indizieren kann.
Für Azure Blob Storage können Sie einen virtuellen Ordner innerhalb des Blobcontainers angeben. Für den Blobpfad mycontainer/documents/blob.pdf kann beispielsweise documents als virtueller Ordner verwendet werden.
Für Azure Table Storage können Sie eine Abfrage angeben, die den Satz der zu importierenden Zeilen filtert.
Für Azure SQL wird die Abfrage nicht unterstützt. Verwenden Sie stattdessen Ansichten.
dataChangeDetectionPolicy Optional. Wird verwendet, um geänderte Datenelemente zu identifizieren. Unterstützte Richtlinien hängen vom Typ der Datenquelle ab. Gültige Richtlinien sind die Richtlinie für die Erkennung hoher Wasserzeichenänderungen und die integrierte SQL-Änderungserkennungsrichtlinie.

Die Erkennungsrichtlinie für hohe Wasserzeichenänderungen hängt von einer vorhandenen Spalte oder Eigenschaft ab, die zusammen mit anderen Updates aktualisiert wird (alle Einfügungen führen zu einer Aktualisierung der Wasserzeichenspalte), und die Änderung des Werts ist höher. Für Cosmos DB-Datenquellen müssen Sie die _ts -Eigenschaft verwenden. Für Azure SQL ist eine indizierte rowversion Spalte der ideale Kandidat für die Verwendung mit der High-Water-Mark-Richtlinie. Für Azure Storage ist die Änderungserkennung mit lastModified-Werten integriert, sodass die dataChangeDetectionPolicy für Blob- oder Tabellenspeicher nicht mehr festgelegt werden muss.

Die integrierte SQL-Änderungserkennungsrichtlinie wird verwendet, um auf die nativen Änderungserkennungsfeatures in SQL Server zu verweisen. Diese Richtlinie kann nur mit Tabellen verwendet werden. Sie kann nicht mit Ansichten verwendet werden. Sie müssen die Änderungsnachverfolgung für die verwendete Tabelle aktivieren, bevor Sie diese Richtlinie verwenden können. Anweisungen finden Sie unter Aktivieren und Deaktivieren der Änderungsnachverfolgung . Weitere Informationen zur Unterstützung der Änderungserkennung im Indexer finden Sie unter Herstellen einer Verbindung mit und Indizieren Azure SQL Inhalten.
dataDeletionDetectionPolicy Optional. Wird verwendet, um gelöschte Datenelemente zu identifizieren. Derzeit wird nur die Richtlinie für vorläufiges Löschen unterstützt, die gelöschte Elemente basierend auf dem Wert einer Spalte oder Eigenschaft des vorläufigen Löschens in der Datenquelle identifiziert.

Es werden nur Spalten mit Zeichenfolgen-, Ganzzahl- oder booleschen Werten unterstützt. Der Wert für softDeleteMarkerValue muss eine Zeichenfolge sein, selbst wenn die entsprechende Spalte Ganzzahlen oder boolesche Werte enthält. Wenn beispielsweise der Wert, der in Ihrer Datenquelle angezeigt wird, 1 ist, verwenden Sie "1" als softDeleteMarkerValue.
encryptionKey Optional. Wird verwendet, um die ruhende Datenquelle mit Ihren eigenen Schlüsseln zu verschlüsseln, die in Ihrem Azure-Key Vault verwaltet werden. Verfügbar für abrechenbare Suchdienste, die am oder nach dem 01.01.2019 erstellt wurden.

Ein encryptionKey Abschnitt enthält einen benutzerdefinierten keyVaultKeyName (erforderlich), einen systemgenerierten keyVaultKeyVersion (erforderlich) und einen keyVaultUri Schlüssel, der den Schlüssel bereitstellt (erforderlich, auch als DNS-Name bezeichnet). Ein Beispiel-URI kann "https://my-keyvault-name.vault.azure.net"" sein.

Optional können Sie angeben accessCredentials , ob Sie keine verwaltete Systemidentität verwenden. Eigenschaften von accessCredentials include applicationId (Microsoft Entra ID Anwendungs-ID, der Zugriffsberechtigungen für Ihre angegebene Azure-Key Vault erteilt wurden), und applicationSecret (Authentifizierungsschlüssel der registrierten Anwendung). Ein Beispiel im nächsten Abschnitt veranschaulicht die Syntax.

Antwort

Bei erfolgreicher Anforderung: "201 Erstellt".

Beispiele

Beispiel: Azure SQL mit Änderungserkennung (Richtlinie zur Erkennung hoher Wasserzeichenänderungen)

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

Beispiel: Azure SQL mit Änderungserkennung (SQL Integrated Änderungsnachverfolgung 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" }
}

Beispiel: Azure SQL mit Änderungserkennung mit Löscherkennung

Beachten Sie, dass die Eigenschaften für die Löscherkennung und softDeleteMarkerValuesindsoftDeleteColumnName.

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

Beispiel: Datenquelle nur mit erforderlichen Eigenschaften

Optionale Eigenschaften im Zusammenhang mit der Änderungs- und Löscherkennung können weggelassen werden, wenn Sie die Datenquelle nur für eine einmalige Kopie der Daten verwenden möchten:

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

Beispiel: Weglassen von Anmeldeinformationen

Wenn Sie die Datenquelle aktualisieren möchten, sind die Anmeldeinformationen nicht erforderlich. Die Werte <unchanged> oder <redacted> können anstelle des Verbindungszeichenfolge verwendet werden.

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

Beispiel: Verschlüsselungsschlüssel

Verschlüsselungsschlüssel sind kundenseitig verwaltete Schlüssel, die für die zusätzliche Verschlüsselung verwendet werden. Weitere Informationen finden Sie unter Verschlüsselung mithilfe von kundenseitig verwalteten Schlüsseln in 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)"}
      }
}

Weitere Informationen