Indicizzare i dati da Archiviazione tabelle di Azure
Questo articolo illustra come configurare un indicizzatore che importa contenuto da Archiviazione tabelle di Azure e lo rende ricercabile in Azure AI Search. Gli input per l'indicizzatore sono le entità, in una singola tabella. L'output è un indice di ricerca con contenuto ricercabile e metadati archiviati in singoli campi.
Questo articolo integra Creare un indicizzatore con informazioni specifiche per l'indicizzazione da Archiviazione tabelle di Azure. Usa le API REST e portale di Azure per illustrare un flusso di lavoro in tre parti comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione di dati si verifica all’invio della richiesta Crea indicizzatore.
Prerequisiti
Tabelle contenenti testo. Se si dispone di dati binari, prendere in considerazione l’Arricchimento tramite intelligenza artificiale per l'analisi delle immagini.
Autorizzazioni di lettura in Archiviazione di Azure. Un stringa di connessione "accesso completo" include una chiave che consente l'accesso al contenuto, ma se si usano i ruoli di Azure, assicurarsi che l'identità gestita del servizio di ricerca disponga delle autorizzazioni lettore e accesso ai dati.
Per esaminare gli esempi in questo articolo, è necessario il portale di Azure o un client REST. Se si usa portale di Azure, assicurarsi che l'accesso a tutte le reti pubbliche sia abilitato. Altri approcci per la creazione di un indicizzatore di tabelle di Azure includono Azure SDK.
Provare con i dati di esempio
Usare queste istruzioni per creare una tabella in Archiviazione di Azure a scopo di test.
Accedere al portale di Azure, passare all'account di archiviazione e creare una tabella denominata hotels.
Scaricare HotelsData_toAzureSearch.csv da GitHub. Questo file è un subset del set di dati di esempio di hotel predefiniti. Omette la raccolta di sale, le descrizioni tradotte e le coordinate geografiche.
In Archiviazione di Azure Explorer accedere ad Azure, selezionare la sottoscrizione e quindi selezionare l'account di archiviazione.
Aprire Tabelle e selezionare hotel.
Selezionare Importa sulla barra dei comandi e quindi selezionare il file HotelsData_toAzureSearch.csv .
Accettare i valori predefiniti. Selezionare Importa per caricare i dati.
Nella tabella devono essere presenti 50 record hotel con partitionKey, rowKey e timestamp generati automaticamente. È ora possibile usare questo contenuto per l'indicizzazione nel portale di Azure, nel client REST o in Azure SDK.
Il campo Descrizione fornisce il contenuto più dettagliato. È consigliabile specificare come destinazione questo campo per la ricerca full-text e le query vettoriali facoltative.
Usare il portale di Azure
È possibile usare la procedura guidata Importa dati o Importare e vettorizzare i dati per automatizzare l'indicizzazione da una tabella o una vista di database SQL. La configurazione dell'origine dati è simile per entrambe le procedure guidate.
In Connetti ai dati selezionare o verificare che il tipo di origine dati sia Archiviazione tabelle di Azure o che i campi di selezione dei dati richiedono tabelle.
Il nome dell'origine dati fa riferimento all'oggetto connessione all'origine dati in Ricerca di intelligenza artificiale di Azure. Se si usa la procedura guidata vettoriale, il nome dell'origine dati viene generato automaticamente usando un prefisso personalizzato specificato alla fine del flusso di lavoro della procedura guidata.
Specificare l'account di archiviazione e il nome della tabella. La query è facoltativa. È utile se sono presenti colonne specifiche da importare.
Specificare un metodo di autenticazione, ovvero un'identità gestita o una chiave API predefinita. Se non si specifica una connessione di identità gestita, il portale usa la chiave .
Se si configura Ricerca intelligenza artificiale di Azure per l'uso di un'identità gestita e si crea un'assegnazione di ruolo in Archiviazione di Azure che concede autorizzazioni di lettura e accesso ai dati per l'identità, l'indicizzatore può connettersi all'archiviazione tabelle usando l'ID e i ruoli di Microsoft Entra.
Per la procedura guidata Importa e vettorizza dati , è possibile specificare le opzioni per il rilevamento dell'eliminazione,
Per il rilevamento dell'eliminazione è necessario disporre di un campo preesistente nella tabella che può essere usato come flag di eliminazione temporanea. Deve essere un campo booleano (è possibile denominarlo IsDeleted). Specificare
truecome valore di eliminazione temporanea. Nell'indice di ricerca aggiungere un campo di ricerca corrispondente denominato IsDeleted impostato su recuperabile e filtrabile.Continuare con i passaggi rimanenti per completare la procedura guidata:
Usare le API REST
Questa sezione illustra le chiamate API REST che creano un'origine dati, un indice e un indicizzatore.
Definire l'origine dati
La definizione dell'origine dati specifica i dati di origine da indicizzare, credenziali e criteri per il rilevamento delle modifiche. Un'origine dati è una risorsa indipendente che può essere usata da più indicizzatori.
Creare o aggiornare un'origine dati per impostarne la definizione:
POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 { "name": "my-table-storage-ds", "description": null, "type": "azuretable", "subtype": null, "credentials": { "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>" }, "container": { "name": "my-table-in-azure-storage", "query": "" }, "dataChangeDetectionPolicy": null, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }Impostare "type" su
"azuretable"(obbligatorio).Impostare "credenziali" su una stringa di connessione di Archiviazione di Azure. Nella sezione successiva vengono descritti i formati supportati.
Impostare "contenitore" sul nome della tabella.
Facoltativamente, impostare "query" su un filtro in PartitionKey. L'impostazione di questa proprietà è una procedura consigliata che migliora le prestazioni. Se "query" è Null, l'indicizzatore esegue una scansione di tabella completa, che può comportare prestazioni scarse se le tabelle sono di grandi dimensioni.
Una definizione di origine dati può includere anche criteri di eliminazione temporanea, se si desidera che l'indicizzatore elimini un documento di ricerca quando il documento di origine viene contrassegnato per l'eliminazione.
Credenziali e stringhe di connessione supportate
Gli indicizzatori possono connettersi a una tabella usando le connessioni seguenti.
| Stringa di connessione dell'account di archiviazione per accesso completo |
|---|
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" } |
| È possibile ottenere la stringa di connessione dalla pagina Account di archiviazione nel portale di Azure selezionando Chiavi di accesso nel riquadro di spostamento sinistro. Assicurarsi di selezionare una stringa di connessione completa e non soltanto una chiave. |
| Stringa di connessione con identità gestita |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" } |
| Questa stringa di connessione non richiede una chiave dell'account, ma è necessario aver configurato in precedenza un servizio di ricerca per la connessione tramite un'identità gestita. |
| Stringa di connessione dell'account di archiviazione con firma di accesso condiviso** (SAS) |
|---|
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" } |
| La firma di accesso condiviso deve disporre delle autorizzazioni di elenco e lettura per tabelle ed entità. |
| Firma di accesso condiviso per il contenitore |
|---|
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" } |
| La firma di accesso condiviso deve avere le autorizzazioni per le operazioni di elenco e lettura sul contenitore. Per altre informazioni, vedere Uso delle firme di accesso condiviso. |
Nota
Se si usano le credenziali di firma di accesso condiviso, sarà necessario aggiornare periodicamente le credenziali dell'origine dati con firme rinnovate per impedire che scadano. Quando le credenziali di firma di accesso condiviso dovessero scadere, l'indicizzatore avrà esito negativo con un messaggio di errore simile al seguente: "Le credenziali specificate nella stringa di connessione non sono valide o sono scadute".
Partizione per migliorare le prestazioni
Per impostazione predefinita, Azure AI Search usa il filtro di query interno seguente per tenere traccia delle entità di origine aggiornate dall'ultima esecuzione: Timestamp >= HighWaterMarkValue. Poiché le tabelle di Azure non dispongono di un indice secondario nel campo Timestamp, questo tipo di query richiede un'analisi completa delle tabelle e risulta pertanto lenta nell'analisi delle tabelle di grandi dimensioni.
Per evitare un'analisi completa, è possibile usare le partizioni di tabella per restringere l'ambito di ogni processo dell'indicizzatore.
Se i dati possono essere partizionati naturalmente in diversi intervalli della partizione, creare un'origine dati e un indicizzatore corrispondente per ogni intervallo della partizione. Ogni indicizzatore deve a questo punto elaborare un solo intervallo specifico della partizione e ciò va a vantaggio delle prestazioni della query. Se i dati da indicizzare hanno un numero ridotto di partizioni fisse, è ancora meglio, perché ciascun indicizzatore analizza solo una partizione.
Per creare ad esempio un'origine dati per l'elaborazione di un intervallo della partizione con le chiavi da
000a100, usare una query simile alla seguente:"container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }Se i dati sono partizionati in base all'ora (ad esempio, se si crea una nuova partizione ogni giorno o ogni settimana), considerare l'approccio seguente:
Nella definizione dell'origine dati specificare una query simile all'esempio seguente:
(PartitionKey ge <TimeStamp>) and (other filters).Monitorare lo stato dell'indicizzatore usando l'API Get Indexer Status (Ottenere lo stato dell'indicizzatore) e aggiornare periodicamente la condizione
<TimeStamp>della query in base al valore limite massimo corretto più recente.Con questo approccio, se è necessario attivare una reindicizzazione completa, reimpostare la query dell'origine dati oltre a reimpostare l'indicizzatore.
Aggiungere campi di ricerca a un indice
In un indice di ricerca, aggiungere campi per accettare il contenuto e i metadati delle entità di tabella.
Creare o aggiornare un indice per definire i campi di ricerca che conserveranno il contenuto delle entità:
POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 { "name" : "my-search-index", "fields": [ { "name": "Key", "type": "Edm.String", "key": true, "searchable": false }, { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true } ] }Creare un campo chiave documento ("chiave": true), ma consentire all'indicizzatore di popolarlo automaticamente. Un indicizzatore di tabella popola il campo chiave con le chiavi di partizione e riga concatenate dalla tabella. Se ad esempio il parametro PartitionKey di una riga è
1e il parametro RowKey è1_123, il valore della chiave è11_123. Se la chiave di partizione è Null, viene usata solo la chiave di riga.Se si usa la procedura guidata Importa dati per creare l'indice, il portale deduce un campo "Chiave" per l'indice di ricerca e usa un mapping dei campi implicito per connettere i campi di origine e di destinazione. Non è necessario aggiungere il campo manualmente e non è necessario configurare un mapping dei campi.
Se si usano le API REST e si desidera un mapping dei campi implicito, è necessario creare e assegnare un nome al campo chiave del documento "Chiave" nella definizione dell'indice di ricerca, come illustrato nel passaggio precedente (
{ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). L'indicizzatore popola automaticamente il campo Chiave senza il mapping dei campi necessario.Se non si desidera un campo denominato "Chiave" nell'indice di ricerca, aggiungere un mapping dei campi esplicito nella definizione dell'indicizzatore con il nome del campo desiderato, impostando il campo di origine su "Chiave":
"fieldMappings" : [ { "sourceFieldName" : "Key", "targetFieldName" : "MyDocumentKeyFieldName" } ]Aggiungere ora tutti gli altri campi di entità desiderati nell'indice. Ad esempio, se un'entità è simile all'esempio seguente, l'indice di ricerca deve contenere campi per HotelName, Description e Category per ricevere tali valori.
L'uso degli stessi nomi e dei tipi di dati compatibili riduce al minimo la necessità di mapping dei campi. Quando i nomi e i tipi sono uguali, l'indicizzatore può determinare automaticamente il percorso dei dati.
Configurare ed eseguire l'indicizzatore di tabelle
Dopo aver creato un indice e un'origine dati, si è pronti per creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti della fase di esecuzione.
Creare o aggiornare l'indicizzatore assegnandogli un nome e il riferimento all’origine dati e all'indice di destinazione:
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01 { "name" : "my-table-indexer", "dataSourceName" : "my-table-storage-ds", "targetIndexName" : "my-search-index", "disabled": null, "schedule": null, "parameters" : { "batchSize" : null, "maxFailedItems" : null, "maxFailedItemsPerBatch" : null, "configuration" : { } }, "fieldMappings" : [ ], "cache": null, "encryptionKey": null }Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo oppure se sono necessarie più versioni di un campo di origine nell'indice di ricerca. Il campo Target è il nome del campo nell'indice di ricerca.
"fieldMappings" : [ { "sourceFieldName" : "Description", "targetFieldName" : "HotelDescription" } ]Per ulteriori informazioni su altre proprietà, vedere Creare un indicizzatore.
Un indicizzatore viene eseguito automaticamente al momento della sua creazione. È possibile ovviare a questo problema impostando "disabilitato" su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.
Controllare lo stato dell'indicizzatore
Per monitorare lo stato dell'indicizzatore e la cronologia di esecuzione, controllare la cronologia di esecuzione dell'indicizzatore nella portale di Azure o inviare un'API REST Get Indexer Status (Ottieni stato dell'indicizzatore)
Nella pagina del servizio di ricerca aprire Indicizzatori di gestione>della ricerca.
Selezionare un indicizzatore per accedere alla cronologia di configurazione ed esecuzione.
Selezionare un processo dell'indicizzatore specifico per visualizzare dettagli, avvisi ed errori.
La cronologia di esecuzione contiene fino a 50 esecuzioni completate più recenti in ordine cronologico inverso, in modo che l'esecuzione più recente venga visualizzata per prima.
Passaggi successivi
Altre informazioni su come eseguire l'indicizzatore, monitorare lo stato o pianificare l'esecuzione dell'indicizzatore. Gli articoli seguenti si applicano agli indicizzatori che eseguono il pull di contenuto da Archiviazione di Azure: