Tworzenie źródła danych (interfejs API REST usługi Azure AI Search)

  • Artykuł

W usłudze Azure AI Search źródło danych jest używane z indeksatorami, dostarczając informacje o połączeniu na żądanie lub zaplanowane odświeżanie danych indeksu docelowego, ściągając dane z obsługiwanych źródeł danych platformy Azure.

Możesz użyć metody POST lub PUT na żądanie. W przypadku jednej z nich dokument JSON w treści żądania zawiera definicję obiektu.

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

Alternatywnie możesz użyć funkcji PUT i określić nazwę identyfikatora URI.

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

Protokół HTTPS jest wymagany dla wszystkich żądań obsługi. Jeśli obiekt nie istnieje, zostanie utworzony. Jeśli już istnieje, zostanie ona zaktualizowana do nowej definicji.

Uwaga

Maksymalna liczba indeksów, które można utworzyć, różni się w zależności od warstwy cenowej. Aby uzyskać więcej informacji, zobacz Limity usługi.

Parametry identyfikatora URI

Parametr Opis
nazwa usługi Wymagane. Ustaw tę wartość na unikatową, zdefiniowaną przez użytkownika nazwę usługi wyszukiwania.
nazwa źródła danych Wymagane dla identyfikatora URI w przypadku używania funkcji PUT. Nazwa musi mieć małe litery, zaczynać się literą lub cyfrą, nie ma ukośników ani kropek i ma mniej niż 128 znaków. Nazwa musi zaczynać się literą lub cyfrą, ale pozostała część nazwy może zawierać dowolną literę, cyfrę i kreski, o ile kreski nie są kolejne.
api-version Wymagane. Zobacz Wersje interfejsu API , aby uzyskać listę obsługiwanych wersji.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Pola Opis
Content-Type Wymagane. Ustaw tę wartość na application/json
api-key Opcjonalnie, jeśli używasz ról platformy Azure , a token elementu nośnego jest dostarczany w żądaniu, w przeciwnym razie wymagany jest klucz. Tworzenie żądań musi zawierać api-key nagłówek ustawiony na klucz administratora (w przeciwieństwie do klucza zapytania). Aby uzyskać szczegółowe informacje, zobacz Nawiązywanie połączenia z usługą Azure AI Search przy użyciu uwierzytelniania klucza .

Treść żądania

Treść żądania zawiera definicję źródła danych, która zawiera typ źródła danych, poświadczenia do odczytu danych, a także opcjonalne zasady wykrywania zmian danych i wykrywania usuwania danych, które są używane do efektywnego identyfikowania zmienionych lub usuniętych danych w źródle danych, gdy są używane z okresowo zaplanowanym indeksatorem.

Poniższy kod JSON jest ogólną reprezentacją głównych części definicji.

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

Żądanie zawiera następujące właściwości:

Właściwość Opis
name Wymagane. Nazwa źródła danych. Nazwa źródła danych musi zawierać tylko małe litery, cyfry lub kreski, nie może zaczynać ani kończyć się kreskami i jest ograniczona do 128 znaków.
description (opis) Opcjonalny opis.
typ Wymagane. Musi być jednym z obsługiwanych typów źródeł danych:

azuresql dla usługi Azure SQL Database, Azure SQL Managed Instance lub wystąpienia SQL Server uruchomionego na maszynie wirtualnej
cosmosdb platformy Azure dla usługi Azure Cosmos DB for NoSQL, Azure Cosmos DB dla bazy danych MongoDB (wersja zapoznawcza) lub Usługi Azure Cosmos DB dla platformy Apache Gremlin (wersja zapoznawcza)
azureblob for Azure Blob Storage
adlsgen2 for Azure Data Lake Storage Gen2
azuretable for Azure Table Storage
azurefile for Azure Files (wersja zapoznawcza)
mysql for Azure Database for MySQL ( wersja zapoznawcza)
sharepoint dla programu SharePoint w rozwiązaniu Microsoft 365 (wersja zapoznawcza)
poświadczenia Wymagane. Zawiera właściwość określającą connectionString parametry połączenia dla źródła danych. Format parametry połączenia zależy od typu źródła danych:

w przypadku Azure SQL Database jest to zwykle SQL Server parametry połączenia. Jeśli używasz Azure Portal do pobrania parametry połączenia, wybierz ADO.NET connection string opcję .

W przypadku usługi Azure Cosmos DB parametry połączenia musi mieć następujący format: "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]". Wszystkie wartości są wymagane. Można je znaleźć w Azure Portal.

W przypadku Azure Blob Storage formaty parametry połączenia są definiowane w sekcji Poświadczenia w temacie How to configure blob indexing in Azure AI Search (Jak skonfigurować indeksowanie obiektów blob w usłudze Azure AI Search).

Usługa Azure Storage, usługa Azure SQL Database i usługa Azure Cosmos DB obsługują również tożsamość zarządzaną parametry połączenia, która nie zawiera klucza konta w parametry połączenia. Aby użyć tożsamości zarządzanej w formacie parametry połączenia, postępuj zgodnie z instrukcjami dotyczącymi konfigurowania połączenia indeksatora ze źródłem danych przy użyciu tożsamości zarządzanej.

Jeśli aktualizujesz źródło danych, parametry połączenia nie jest wymagana. Wartości <unchanged> lub <redacted> mogą być używane zamiast rzeczywistej parametry połączenia.
kontener Wymagane. Określa dane do indeksowania przy użyciu name (wymagane) i query (opcjonalnie) właściwości: :

name
dla Azure SQL określa tabelę lub widok. Możesz użyć nazw kwalifikowanych schematem, takich jak [dbo].[mytable].
W przypadku usługi Azure Cosmos DB określa kolekcję interfejsów API SQL.
W przypadku Azure Blob Storage określa kontener magazynu.
W przypadku usługi Azure Table Storage określa nazwę tabeli.

query:
W przypadku usługi Azure Cosmos DB można określić zapytanie, które spłaszcza dowolny układ dokumentu JSON w płaski schemat, który usługa Azure AI Search może indeksować.
W przypadku Azure Blob Storage umożliwia określenie folderu wirtualnego w kontenerze obiektów blob. Na przykład dla ścieżki mycontainer/documents/blob.pdfdocuments obiektu blob można użyć jako folderu wirtualnego.
W przypadku usługi Azure Table Storage można określić zapytanie, które filtruje zestaw wierszy do zaimportowania.
W przypadku Azure SQL zapytanie nie jest obsługiwane. Zamiast tego użyj widoków.
dataChangeDetectionPolicy Opcjonalny. Służy do identyfikowania zmienionych elementów danych. Obsługiwane zasady różnią się w zależności od typu źródła danych. Prawidłowe zasady to zasady wykrywania zmian z wysokim znakiem wodnym i zintegrowane zasady wykrywania zmian SQL.

Zasady wykrywania zmian z wysokim znakiem wodnym zależą od istniejącej kolumny lub właściwości, która jest aktualizowana razem z innymi aktualizacjami (wszystkie wstawia wynik aktualizacji do kolumny limitu), a zmiana wartości jest wyższa. W przypadku źródeł danych usługi Cosmos DB należy użyć _ts właściwości . W przypadku Azure SQL indeksowana rowversion kolumna jest idealnym kandydatem do użycia z zasadami wysokiego znaku wodnego. W przypadku usługi Azure Storage wykrywanie zmian jest wbudowane przy użyciu wartości lastModified, eliminując konieczność ustawiania zasad dataChangeDetectionPolicy dla magazynu obiektów blob lub tabel.

Zintegrowane zasady wykrywania zmian SQL służą do odwoływanie się do natywnych funkcji wykrywania zmian w SQL Server. Te zasady mogą być używane tylko z tabelami; nie można jej używać z widokami. Przed użyciem tych zasad należy włączyć śledzenie zmian dla tabeli, której używasz. Aby uzyskać instrukcje, zobacz Włączanie i wyłączanie śledzenia zmian . Aby uzyskać więcej informacji na temat obsługi wykrywania zmian w indeksatorze, zobacz Nawiązywanie połączenia z zawartością Azure SQL i indeksowanie.
dataDeletionDetectionPolicy Opcjonalny. Służy do identyfikowania usuniętych elementów danych. Obecnie jedynymi obsługiwanymi zasadami są zasady usuwania nietrwałego, które identyfikują usunięte elementy na podstawie wartości kolumny lub właściwości usuwania nietrwałego w źródle danych.

Obsługiwane są tylko kolumny z wartościami ciągowymi, całkowitymi lub logicznymi. Wartość używana jako softDeleteMarkerValue musi być ciągiem, nawet jeśli odpowiednia kolumna zawiera liczby całkowite lub wartości logiczne. Jeśli na przykład wartość wyświetlana w źródle danych to 1, użyj wartości "1" jako .softDeleteMarkerValue
encryptionKey Opcjonalny. Służy do szyfrowania źródła danych magazynowanych przy użyciu własnych kluczy zarządzanych w usłudze Azure Key Vault. Dostępne dla rozliczanych usług wyszukiwania utworzonych w dniach lub po 2019-01-01.

Sekcja encryptionKey zawiera zdefiniowaną przez keyVaultKeyName użytkownika (wymaganą), wygenerowaną keyVaultKeyVersion przez system (wymaganą keyVaultUri ) i podając klucz (wymagany, nazywany również nazwą DNS). Przykładowy identyfikator URI może mieć wartość "https://my-keyvault-name.vault.azure.net"".

Opcjonalnie możesz określić accessCredentials , czy nie używasz tożsamości systemu zarządzanego. Właściwości dołączania accessCredentialsapplicationId (Tożsamość Microsoft Entra identyfikatora aplikacji, któremu udzielono uprawnień dostępu do określonej Key Vault platformy Azure) i applicationSecret (klucz uwierzytelniania zarejestrowanej aplikacji). Przykład w następnej sekcji ilustruje składnię.

Reakcja

W przypadku pomyślnego żądania: 201 Utworzono.

Przykłady

Przykład: Azure SQL z wykrywaniem zmian (zasady wykrywania zmian z wysokim znakiem wodnym)

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

Przykład: Azure SQL z wykrywaniem zmian (zintegrowane zasady 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" }
}

Przykład: Azure SQL z wykrywaniem zmian z wykrywaniem usuwania

Pamiętaj, że właściwości wykrywania usuwania to softDeleteColumnName i 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" }  
}

Przykład: źródło danych z wymaganymi właściwościami

Opcjonalne właściwości związane z wykrywaniem zmian i usuwania można pominąć, jeśli zamierzasz używać źródła danych tylko na jednorazową kopię danych:

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

Przykład: pomijanie poświadczeń

Jeśli zamierzasz zaktualizować źródło danych, poświadczenia nie są wymagane. Wartości <unchanged> lub <redacted> mogą być używane zamiast parametry połączenia.

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

Przykład: klucze szyfrowania

Klucze szyfrowania to klucze zarządzane przez klienta używane do dodatkowego szyfrowania. Aby uzyskać więcej informacji, zobacz Szyfrowanie przy użyciu kluczy zarządzanych przez klienta w usłudze 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)"}
      }
}

Zobacz też