Creare un'origine dati (API REST di Ricerca intelligenza artificiale di Azure)

Articolo
03/05/2024

In Ricerca di intelligenza artificiale di Azure viene usata un'origine dati con gli indicizzatori, fornendo le informazioni di connessione per l'aggiornamento dati su richiesta o pianificato di un indice di destinazione, estraendo i dati dalle origini dati di Azure supportate.

È possibile usare POST o PUT nella richiesta. Per entrambi, il documento JSON nel corpo della richiesta fornisce la definizione dell'oggetto.

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

In alternativa, è possibile usare PUT e specificare il nome nell'URI.

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

Per tutte le richieste del servizio, è necessario usare il protocollo HTTPS. Se l'oggetto non esiste, viene creato. Se esiste già, viene aggiornato alla nuova definizione.

Nota

Il numero massimo di indici che è possibile creare varia in base al piano tariffario. Per altre informazioni, vedere Limiti del servizio.

Parametri dell'URI

Parametro	Descrizione
nome servizio	Obbligatorio. Impostarlo sul nome univoco definito dall'utente del servizio di ricerca.
nome origine dati	Obbligatorio nell'URI se si usa PUT. Il nome deve essere minuscolo, iniziare con una lettera o un numero, non avere barre o punti e contenere meno di 128 caratteri. Il nome deve iniziare con una lettera o un numero, ma il resto del nome può includere qualsiasi lettera, numero e trattino, purché i trattini non siano consecutivi.
api-version	Obbligatorio. Per un elenco delle versioni supportate, vedere Versioni API .

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Campi Descrizione

Content-Type Obbligatorio. Impostare il valore su application/json

api-key Facoltativo se si usano i ruoli di Azure e viene fornito un token di connessione nella richiesta, in caso contrario è necessaria una chiave. Le richieste di creazione devono includere un'intestazione api-key impostata sulla chiave amministratore anziché su una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave .

Campi	Descrizione
Content-Type	Obbligatorio. Impostare il valore su `application/json`
api-key	Facoltativo se si usano i ruoli di Azure e viene fornito un token di connessione nella richiesta, in caso contrario è necessaria una chiave. Le richieste di creazione devono includere un'intestazione `api-key` impostata sulla chiave amministratore anziché su una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione della chiave .

Corpo della richiesta

Il corpo della richiesta contiene una definizione dell'origine dati, che include il tipo di origine dati, le credenziali per leggere i dati, oltre a criteri facoltativi di rilevamento delle modifiche dei dati e dell'eliminazione dei dati usati per identificare in modo efficiente i dati modificati o eliminati nell'origine dati, quando vengono usati con un indicizzatore pianificato periodicamente.

Il codice JSON seguente è una rappresentazione generale delle parti principali della definizione.

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

La richiesta contiene le proprietà seguenti:

Proprietà	Descrizione
name	Obbligatorio. Nome dell'origine dati. Un nome di origine dati deve contenere solo lettere minuscole, cifre o trattini, non può iniziare o terminare con trattini ed è limitato a 128 caratteri.
description	Descrizione facoltativa.
tipo	Obbligatorio. Deve essere uno dei tipi di origine dati supportati: `azuresql` per database di Azure SQL, Istanza gestita di SQL di Azure o SQL Server'istanza in esecuzione nella macchina virtuale `cosmosdb` di Azure per Azure Cosmos DB per NoSQL, Azure Cosmos DB per MongoDB (anteprima) o Azure Cosmos DB per Apache Gremlin (anteprima) `azureblob` per Archiviazione BLOB di Azure `adlsgen2` per Azure Data Lake Storage Gen2 `azuretable` per Archiviazione tabelle di `azurefile` Azure per File di Azure (anteprima) `mysql` per Database di Azure per MySQL (anteprima) `sharepoint` per SharePoint in Microsoft 365(anteprima)
credentials	Obbligatorio. Contiene una `connectionString` proprietà che specifica il stringa di connessione per l'origine dati. Il formato del stringa di connessione dipende dal tipo di origine dati: per Azure SQL Database, si tratta del normale SQL Server stringa di connessione. Se si usa portale di Azure per recuperare il stringa di connessione, scegliere l'opzione `ADO.NET connection string` . Per Azure Cosmos DB, il stringa di connessione deve essere nel formato seguente: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Tutti i valori sono obbligatori e sono reperibili nel portale di Azure. Per Archiviazione BLOB di Azure, i formati di stringa di connessione vengono definiti nella sezione Credenziali di Come configurare l'indicizzazione BLOB in Ricerca di intelligenza artificiale di Azure. Archiviazione di Azure, database Azure SQL e Azure Cosmos DB supportano anche un'identità gestita stringa di connessione che non include una chiave dell'account nel stringa di connessione. Per usare il formato di identità gestita stringa di connessione, seguire le istruzioni per Configurare una connessione dell'indicizzatore a un'origine dati usando un'identità gestita. Se si aggiorna l'origine dati, il stringa di connessione non è necessario. I valori `<unchanged>` o `<redacted>` possono essere usati al posto del stringa di connessione effettivo.
contenitore	Obbligatorio. Specifica i dati da indicizzare utilizzando le `name` proprietà`name` (obbligatorie) e `query` (facoltative): : per Azure SQL, specifica la tabella o la vista. È possibile usare nomi completi di schema, ad esempio `[dbo].[mytable]`. Per Azure Cosmos DB, specifica la raccolta di API SQL. Per Archiviazione BLOB di Azure, specifica il contenitore di archiviazione. Per Archiviazione tabelle di Azure, specifica il nome della tabella. `query`: per Azure Cosmos DB, consente di specificare una query che rende flat un layout di documento JSON arbitrario in uno schema flat che Ricerca intelligenza artificiale di Azure può indicizzare. Per Archiviazione BLOB di Azure, consente di specificare una cartella virtuale all'interno del contenitore BLOB. Ad esempio, per il percorso BLOB `mycontainer/documents/blob.pdf` è possibile usare `documents` come cartella virtuale. Per Archiviazione tabelle di Azure, consente di specificare una query che filtra il set di righe da importare. Per Azure SQL, la query non è supportata. Usare invece le visualizzazioni.
dataChangeDetectionPolicy	facoltativo. Usato per identificare gli elementi di dati modificati. I criteri supportati variano in base al tipo di origine dati. I criteri validi sono i criteri di rilevamento delle modifiche con filigrana elevata e i criteri di rilevamento delle modifiche integrati di SQL. I criteri di rilevamento modifiche con filigrana elevata dipendono da una colonna o una proprietà esistente che viene aggiornata in combinazione con altri aggiornamenti (tutti gli inserimenti generano un aggiornamento alla colonna limite) e la modifica del valore è superiore. Per le origini dati di Cosmos DB, è necessario usare la `_ts` proprietà . Per Azure SQL, una colonna indicizzata `rowversion` è il candidato ideale per l'uso con i criteri di contrassegno elevato dell'acqua. Per Archiviazione di Azure, il rilevamento delle modifiche è incorporato usando i valori lastModified, eliminando la necessità di impostare dataChangeDetectionPolicy per l'archiviazione BLOB o tabelle. I criteri di rilevamento delle modifiche integrati di SQL vengono usati per fare riferimento alle funzionalità di rilevamento delle modifiche native in SQL Server. Questo criterio può essere usato solo con le tabelle; non può essere usato con le visualizzazioni. Prima di poter usare questi criteri, è necessario abilitare il rilevamento delle modifiche per la tabella in uso. Per istruzioni, vedere Abilitare e disabilitare il rilevamento delle modifiche . Per altre informazioni sul supporto del rilevamento delle modifiche nell'indicizzatore, vedere Connettersi a e indicizzare Azure SQL contenuto.
dataDeletionDetectionPolicy	facoltativo. Usato per identificare gli elementi di dati eliminati. Attualmente, l'unico criterio supportato è il criterio di eliminazione temporanea, che identifica gli elementi eliminati in base al valore di una colonna o una proprietà "eliminazione temporanea" nell'origine dati. Sono supportate solo le colonne con valori stringa, integer o booleani. Il valore usato come `softDeleteMarkerValue` deve essere una stringa, anche se la colonna corrispondente contiene valori interi o booleani. Ad esempio, se il valore visualizzato nell'origine dati è 1, usare "1" come `softDeleteMarkerValue`.
encryptionKey	facoltativo. Usato per crittografare l'origine dati inattivi con le proprie chiavi gestite nel Key Vault di Azure. Disponibile per i servizi di ricerca fatturabili creati in o dopo il 2019-01-01. Una `encryptionKey` sezione contiene un oggetto definito dall'utente `keyVaultKeyName` (obbligatorio), un sistema generato `keyVaultKeyVersion` (obbligatorio) e un `keyVaultUri` oggetto che fornisce la chiave (obbligatoria, nota anche come nome DNS). Un URI di esempio potrebbe essere "https://my-keyvault-name.vault.azure.net". Facoltativamente, è possibile specificare `accessCredentials` se non si usa un'identità del sistema gestito. Le proprietà di `accessCredentials` includono `applicationId` (Microsoft Entra ID ID applicazione a cui sono state concesse le autorizzazioni di accesso per l'Key Vault di Azure specificato) e `applicationSecret` (chiave di autenticazione dell'applicazione registrata). Un esempio nella sezione successiva illustra la sintassi.

Risposta

Se la richiesta ha esito positivo, viene restituito il codice di stato 201 - Creato.

Esempio

Esempio: Azure SQL con rilevamento delle modifiche (criteri di rilevamento modifiche con filigrana elevata)

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

Esempio: Azure SQL con rilevamento delle modifiche (criteri di Rilevamento modifiche integrati di 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" }
}

Esempio: Azure SQL con rilevamento delle modifiche con rilevamento delle eliminazioni

Tenere presente che le proprietà per il rilevamento dell'eliminazione sono softDeleteColumnName e 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" }  
}

Esempio: origine dati solo con proprietà obbligatorie

È possibile omettere le proprietà facoltative correlate al rilevamento delle modifiche e dell'eliminazione se si intende usare l'origine dati solo per una copia occasionale dei dati:

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

Esempio: Omissione di credenziali

Se si intende aggiornare l'origine dati, le credenziali non sono necessarie. I valori <unchanged> o <redacted> possono essere usati al posto del stringa di connessione.

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

Esempio: Chiavi di crittografia

Le chiavi di crittografia sono chiavi gestite dal cliente usate per la crittografia aggiuntiva. Per altre informazioni, vedere Crittografia con chiavi gestite dal cliente 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)"}
      }
}