Condividi tramite

Creare o aggiornare l'origine dati (API REST di anteprima)

  • Articolo

si applica a: 2023-07-01-Preview. Questa versione non è più supportata. Aggiornare immediatamente a una versione più recente.

Importante

2023-07-01-Preview (nessuna modifica).

2021-04-30-Preview aggiunge il supporto delle identità gestite per le connessioni dell'indicizzatore ad altre risorse di Azure:

  • "credenziali" accetta un ID risorsa di Azure come valore, purché il servizio di ricerca venga eseguito con un'identità gestita e le assegnazioni di ruolo di Azure concedono l'accesso in lettura ai dati.
  • "identità" accetta un'identità gestita assegnata dall'utente. Questa proprietà è di primo livello per le connessioni dati. È anche in "encryptionKey" per recuperare una chiave gestita dal cliente in Azure Key Vault.
  • supporto di File di Azure è disponibile in anteprima. Usare un'API di anteprima per indicizzare da questa origine dati.

2020-06-30-Preview aggiunge:

  • "dataDeletionDetectionPolicy" accetta "NativeBlobSoftDeleteDeleteDeletionDetectionPolicy" per gli indicizzatori BLOB.
  • il supporto di Database di Azure per MySQL è disponibile in anteprima. Usare un'API di anteprima per indicizzare da questa origine dati.
  • supporto dell'API MongoDB di Cosmos DB e dell'API Gremlin è disponibile in anteprima. Usare un'API di anteprima per indicizzare da questa origine dati.

In Ricerca di intelligenza artificiale di Azure viene usata un'origine dati con indicizzatori , fornendo le informazioni di connessione per l'aggiornamento dati su richiesta o pianificato di un indice di destinazione, il pull dei dati da origini dati supportate.

È possibile usare POST o PUT in una richiesta di creazione. Per entrambi, il 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]

Per le richieste di aggiornamento, usare PUT e specificare il nome dell'indicizzatore 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]

HTTPS è obbligatorio per tutte le richieste di servizio. Se l'oggetto non esiste, viene creato. Se esiste già, viene sovrascritto usando la nuova definizione.

Nota

Una volta presente un'origine dati, non è possibile modificare la proprietà type in una richiesta di aggiornamento. È invece necessario creare una nuova origine dati usando il tipo desiderato.

Parametri URI

Parametro Descrizione
nome del 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. Dopo aver avviato il nome con una lettera o un numero, il resto del nome può includere qualsiasi lettera, numero e trattini, purché i trattini non siano consecutivi.
api-version Obbligatorio. Per altre versioni, vedere versioni dell'API.

Intestazioni della richiesta

Nella tabella seguente vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Campi Descrizione
Tipo di contenuto Obbligatorio. Impostare questa opzione su application/json
api-key Facoltativo se si usano ruoli di Azure e viene fornito un token di connessione nella richiesta; in caso contrario, è necessaria una chiave. Una chiave API è una stringa univoca generata dal sistema che autentica la richiesta al servizio di ricerca. Le richieste di creazione devono includere un'intestazione api-key impostata sulla chiave di amministrazione , anziché su una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca di 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 dell'origine dati, le credenziali per leggere i dati, nonché i criteri facoltativi di rilevamento delle modifiche ai dati e di 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" : (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)"}
      }
}

La richiesta contiene le proprietà seguenti:

Proprietà Descrizione
nome 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.
descrizione Descrizione facoltativa.
digitare Obbligatorio. Deve essere uno dei tipi di origine dati supportati:

adlsgen2 per
azureblob azure Data Lake Storage Gen2 per
azurefiles di Archiviazione BLOB di Azure per
azuresql archiviazione file di Azure per
azuretable del database SQL di Azure per
cosmosdb di Archiviazione tabelle di Azure per l'API SQL di Azure Cosmos DB , 'API MongoDB,
mysql API Gremlin per Database di Azure per MySQL
credenziali Obbligatorio. Contiene una proprietà connectionString che specifica come connettersi.
contenitore Obbligatorio. Specifica il contenitore, la raccolta, la tabella o la vista contenente i dati da indicizzare.
dataChangeDetectionPolicy Opzionale. Specifica il meccanismo fornito dalla piattaforma dati per identificare gli elementi di dati modificati.
dataDeletionDetectionPolicy Opzionale. Identifica il modo in cui la piattaforma dati elimina i dati.
encryptionKey Opzionale. Usato per una crittografia aggiuntiva delle credenziali dell'origine dati, tramite chiavi di crittografia gestite dal cliente (CMK) in Azure Key Vault. Disponibile per i servizi di ricerca fatturabili creati in o dopo il 2019-01-01.
disabile Opzionale. Valore booleano che indica se l'indicizzatore viene creato in uno stato disabilitato, impedendo l'esecuzione immediata. False per impostazione predefinita.
identità Opzionale. Contiene un userAssignedIdentity di tipo #Microsoft.Azure.Search.DataUserAssignedIdentity e specifica l'identità gestita assegnata dall'utente della risorsa esterna. Questa proprietà dipende da credentials avere la stringa di connessione nel formato corretto (ID risorsa) per le connessioni identity gestite per ogni tipo di origine dati.

Se la proprietà identity è null, la connessione a un ID risorsa viene eseguita usando la proprietà gestita dal sistema.

Se questa proprietà viene assegnata al tipo #Microsoft.Azure.Search.DataNoneIdentity, viene cancellata qualsiasi identità esplicita specificata in precedenza.

Risposta

Per una richiesta con esito positivo: 201 Creato se è stata creata una nuova origine dati e 204 Nessun contenuto se è stata aggiornata un'origine dati esistente.

Esempi

esempio di : ruoli di Azure e un'identità gestita assegnata dal sistema

Se il servizio di ricerca ha un'identità gestita assegnata dal sistema e un'assegnazione di ruolo, la connessione all'origine dati può essere l'ID risorsa univoco dell'account di archiviazione.

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

esempio : ruoli di Azure e un'identità gestita assegnata dall'utente (anteprima)

Questo esempio illustra una connessione autenticata di Azure AD per un servizio di ricerca con un'identità gestita assegnata dall'utente.

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

esempio: Sql di Azure con rilevamento delle modifiche (criteri di rilevamento modifiche con limite elevato)

{   
    "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 di : Sql di Azure con rilevamento delle modifiche (criteri di rilevamento delle modifiche integrati 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 : Sql di Azure 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 con proprietà obbligatorie solo

Le proprietà facoltative correlate al rilevamento delle modifiche e dell'eliminazione possono essere omesse se si intende usare solo l'origine dati per una copia monouso 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 : uso dell'opzione delle credenziali non modificate o modificate

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

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

Esempio di : chiavi di crittografia

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

esempio: Connessioni dell'insieme di credenziali delle chiavi di crittografia da parte dei servizi di ricerca con un'identità gestita assegnata dall'utente

In questo esempio viene omesso accessCredentials. Per una risorsa con una 'identità gestita assegnata dall'utente assegnata, è possibile specificare l'identità in encryptionKey e recuperare la chiave usando tale identità e assegnazioni di ruolo di 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"
        }
    }
}

Definizioni

Collegamento Descrizione
contenitore Specifica il contenitore, la raccolta, la tabella o la vista contenente i dati da indicizzare.
credenziali Contiene una proprietà connectionString che specifica come un indicizzatore si connette a una risorsa di Azure.
dataChangeDetectionPolicy Specifica il meccanismo fornito dalla piattaforma dati per identificare i dati modificati.
dataDeletionDetectionPolicy Specifica il meccanismo per il rilevamento dei dati eliminati.
encryptionKey Configura una connessione ad Azure Key Vault per la crittografia gestita dal cliente.

contenitore

Specifica il contenitore, la raccolta, la tabella o la vista contenente i dati da indicizzare.

Attributo Descrizione
nome Obbligatorio. Per Azure Cosmos DB, specifica la raccolta di API SQL. Per Archiviazione BLOB di Azure, specifica il contenitore di archiviazione. Per Azure SQL specifica la tabella o la vista. È possibile usare nomi qualificati per lo schema, ad esempio [dbo].[mytable]. Per Archiviazione tabelle di Azure, specifica il nome della tabella.
quesito Opzionale. Per Azure Cosmos DB, consente di specificare una query che rende flat il layout di un 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, documents può essere usato 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 viste).

credenziali

Contiene una proprietà "connectionString" che specifica come un indicizzatore si connette a una risorsa di Azure.

Attributo Descrizione
connectionString Obbligatorio. Specifica una connessione a un'origine dati dell'indicizzatore. Se si aggiorna la definizione dell'origine dati, la stringa di connessione non è necessaria. I valori <unchanged> o <redacted> possono essere usati al posto della stringa di connessione effettiva.

Per le connessioni autenticate tramite chiavi o credenziali di accesso, tali valori sono visibili nella stringa di connessione. Il formato della stringa di connessione dipende dal tipo di origine dati:

Per il database SQL di Azure, si tratta della normale stringa di connessione di SQL Server. Se si usa il portale di Azure per recuperare la stringa di connessione, scegliere l'opzione ADO.NET connection string.

Per Azure Cosmos DB, la 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. È possibile trovarli nel portale di Azure .

Se si usa un'identità gestita per autenticare, è possibile omettere le credenziali nella connessione.

Per le connessioni autenticate tramite un'identità gestita, la stringa di connessione specifica l'ID risorsa di Azure . Vedere questi collegamenti per il formato della stringa di connessione: Archiviazione di Azure, Cosmos DB,database SQL).

Le assegnazioni di ruolo con ambito all'origine dati esterna determinano se l'indicizzatore può connettersi e il servizio di ricerca deve essere configurato per l'esecuzione come servizio attendibile in Azure Active Directory.

Se viene specificata anche la proprietà "identity", la connessione viene effettuata usando l'identità gestita assegnata dall'utente del servizio di ricerca fornita dalla proprietà "identity". In caso contrario, se "identity" non è specificato o null, la connessione viene eseguita tramite l'identità gestita dal sistema.

dataChangeDetectionPolicy

Specifica il meccanismo fornito dalla piattaforma dati per identificare i dati modificati. I criteri supportati variano in base al tipo di origine dati.

Attributo Descrizione
dataChangeDetectionPolicy Opzionale. I criteri validi includono HighWatermarkChangeDetectionPolicy o SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy dipende da una colonna o una proprietà esistente aggiornata in combinazione con altri aggiornamenti (tutti gli inserimenti comportano un aggiornamento alla colonna limite) e la modifica del valore è superiore.

SqlIntegratedChangeDetectionPolicy viene usato 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 questo criterio, è necessario abilitare il rilevamento delle modifiche per la tabella in uso. Per istruzioni, vedere abilitare e disabilitare il rilevamento delle modifiche.
highWaterMarkColumnName Obbligatorio per HighWatermarkChangeDetectionPolicy. Per Cosmos DB, la colonna deve essere _ts proprietà. Per Azure SQL è consigliabile usare una colonna rowversion indicizzata. Per Archiviazione di Azure, il rilevamento delle modifiche è incorporato usando i valori lastModified, eliminando la necessità di impostare dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Specifica il meccanismo fornito dalla piattaforma dati per identificare i dati eliminati. I criteri supportati variano in base al tipo di origine dati.

Attributo Descrizione
dataDeletionDetectionPolicy Opzionale. I valori validi sono SoftDeleteColumnDeletionDetectionPolicy o NativeBlobSoftDeleteDeletionDetectionPolicy (vedere eliminazione temporanea blob nativa (anteprima)).

Attualmente, l'unico criterio disponibile a livello generale èSoftDeleteColumnDeletionDetectionPolicy, che identifica gli elementi eliminati in base al valore di una colonna o una proprietà 'eliminazione temporanea' nell'origine dati.

softDeleteColumnName" Obbligatorio. Nome di una colonna nell'origine dati che fornisce un valore che specifica lo stato di eliminazione di una riga. Ad esempio, è possibile creare una colonna denominata "IsDeleted". Sono supportate solo le colonne con valori stringa, integer o booleani.
softDeleteMarkerValue Obbligatorio. Valore della colonna di eliminazione temporanea. Il valore utilizzato come softDeleteMarkerValue deve essere una stringa, anche se la colonna corrispondente contiene numeri interi o booleani. Ad esempio, se il valore visualizzato nell'origine dati è 1, usare "1" come softDeleteMarkerValue. Se l'indicizzatore legge questo valore dalla colonna di eliminazione temporanea, elimina il documento di ricerca corrispondente dall'indice di ricerca.

encryptionKey

Configura una connessione ad Azure Key Vault per chiavi di crittografia gestite dal cliente (CMK). La crittografia con chiavi gestite dal cliente non è disponibile per i servizi gratuiti. Per i servizi fatturabili, è disponibile solo per i servizi di ricerca creati in o dopo il 2019-01-01.

È necessario autenticare una connessione all'insieme di credenziali delle chiavi. A questo scopo, è possibile usare "accessCredentials" o un'identità gestita.

Le identità gestite possono essere assegnate dal sistema o dall'utente (anteprima). Se il servizio di ricerca ha sia un'identità gestita assegnata dal sistema che un'assegnazione di ruolo che concede l'accesso in lettura all'insieme di credenziali delle chiavi, è possibile omettere sia "identity" che "accessCredentials" e la richiesta eseguirà l'autenticazione usando l'identità gestita. Se il servizio di ricerca ha un'identità assegnata dall'utente e un'assegnazione di ruolo, impostare la proprietà "identity" sull'ID risorsa di tale identità.

Attributo Descrizione
keyVaultKeyName Obbligatorio. Nome della chiave di Azure Key Vault usata per la crittografia.
keyVaultKeyVersion Obbligatorio. Versione della chiave di Azure Key Vault.
keyVaultUri Obbligatorio. URI di Azure Key Vault (detto anche nome DNS) che fornisce la chiave. Un URI di esempio potrebbe essere https://my-keyvault-name.vault.azure.net.
accessCredentials Omettere se si usa un'identità gestita. In caso contrario, le proprietà di accessCredentials includono applicationId (un ID applicazione di Azure Active Directory con autorizzazioni di accesso all'insieme di credenziali delle chiavi di Azure specificato) e applicationSecret (chiave di autenticazione dell'applicazione Azure AD specificata).
identità Facoltativo, a meno che non si usi un'identità gestita assegnata dall'utente per la connessione del servizio di ricerca ad Azure Key Vault. Il formato è "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Vedere anche