Condividi tramite

Indicizzare i dati da Archiviazione tabelle di Azure

  • Articolo

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

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.

  1. Accedere al portale di Azure, passare all'account di archiviazione e creare una tabella denominata hotels.

  2. Installare Archiviazione di Azure Explorer.

  3. 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.

  4. In Archiviazione di Azure Explorer accedere ad Azure, selezionare la sottoscrizione e quindi selezionare l'account di archiviazione.

  5. Aprire Tabelle e selezionare hotel.

  6. Selezionare Importa sulla barra dei comandi e quindi selezionare il file HotelsData_toAzureSearch.csv .

  7. 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.

  1. Avvia la procedura guidata.

  2. 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.

  3. Specificare l'account di archiviazione e il nome della tabella. La query è facoltativa. È utile se sono presenti colonne specifiche da importare.

  4. 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 di Azure 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.

  5. 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 true come valore di eliminazione temporanea. Nell'indice di ricerca aggiungere un campo di ricerca corrispondente denominato IsDeleted impostato su recuperabile e filtrabile.

  6. 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.

  1. 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
 }

  2. Impostare "type" su "azuretable" (obbligatorio).

  3. Impostare "credenziali" su una stringa di connessione di Archiviazione di Azure. Nella sezione successiva vengono descritti i formati supportati.

  4. Impostare "contenitore" sul nome della tabella.

  5. 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 000 a 100, 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.

  1. 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 }
  ]
}

  2. 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 è 1 e 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 di Azure deduce un campo "Chiave" per l'indice di ricerca e usa un mapping di campo 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"
   }
]

  3. 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.

    Screenshot del contenuto della tabella nel browser di archiviazione.

    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.

  1. 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
}

  2. 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"
   }
]

  3. 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)

  1. Nella pagina del servizio di ricerca aprire Indicizzatori di gestione>della ricerca.

  2. Selezionare un indicizzatore per accedere alla cronologia di configurazione ed esecuzione.

  3. 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: