Indicizzare i dati dalla tabella di Azure Archiviazione

Questo articolo illustra come configurare un indicizzatore che importa il contenuto dalla tabella di Azure Archiviazione e lo rende ricercabile in Ricerca di intelligenza artificiale di Azure. 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 tabelle di Azure Archiviazione. Usa le API REST 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 dei dati si verifica quando si invia la richiesta Crea indicizzatore.

Prerequisiti

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=2023-11-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 "credentials" su un Archiviazione di Azure stringa di connessione. Nella sezione successiva vengono descritti i formati supportati.

  4. Impostare "container" 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 un'analisi completa della tabella, 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 supportate e stringa di connessione

Gli indicizzatori possono connettersi a una tabella usando le connessioni seguenti.

Stringa di connessione dell'account di archiviazione con accesso completo
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
È possibile ottenere il stringa di connessione dalla pagina dell'account Archiviazione in portale di Azure selezionando Chiavi di accesso nel riquadro di spostamento a sinistra. Assicurarsi di selezionare un stringa di connessione completo e non solo una chiave.
Identità gestita stringa di connessione
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
Questo stringa di connessione non richiede una chiave dell'account, ma è necessario aver configurato in precedenza un servizio di ricerca per la connessione usando un'identità gestita.
Archiviazione firma di accesso condiviso dell'account** (SAS) stringa di connessione
{ "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 del 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, è necessario aggiornare periodicamente le credenziali dell'origine dati con firme rinnovate per impedire la scadenza. Quando le credenziali di firma di accesso condiviso scadono, l'indicizzatore avrà esito negativo con un messaggio di errore simile a "Le credenziali fornite nella stringa di connessione non sono valide o sono scadute".

Partizione per migliorare le prestazioni

Per impostazione predefinita, Ricerca intelligenza artificiale di Azure 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 naturalmente partizionati in più intervalli di partizioni, creare un'origine dati e un indicizzatore corrispondente per ogni intervallo di partizioni. 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.

    Ad esempio, per creare un'origine dati per l'elaborazione di un intervallo di partizioni con 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 vengono partizionati in base all'ora (ad esempio, se si crea una nuova partizione ogni giorno o 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 archivieranno il contenuto dalle entità:

    POST https://[service name].search.windows.net/indexes?api-version=2023-11-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. Ad esempio, se partitionKey di una riga è 1 e 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 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 vogliono mapping di campi impliciti, 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 mapping dei campi necessari.

    Se non si desidera un campo denominato "Key" nell'indice di ricerca, aggiungere un mapping di campo esplicito nella definizione dell'indicizzatore con il nome del campo desiderato, impostando il campo di origine su "Key":

     "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 of table content in Storage browser.

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

  1. Creare o aggiornare un indicizzatore assegnando un nome e facendo riferimento all'origine dati e all'indice di destinazione:

    POST https://[service name].search.windows.net/indexers?api-version=2023-11-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,
            "base64EncodeKeys" : null,
            "configuration" : { }
        },
        "fieldMappings" : [ ],
        "cache": null,
        "encryptionKey": null
    }
    
  2. Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo o 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 altre informazioni sulle altre proprietà, vedere Creare un indicizzatore .

Un indicizzatore viene eseguito automaticamente quando viene creato. È possibile evitare 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, inviare una richiesta Get Indexer Status :To monitor the indexer status and execution history, send a Get Indexer Status request:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe essere simile all'esempio seguente:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

La cronologia di esecuzione contiene fino a 50 delle esecuzioni completate più di recente, ordinate in ordine cronologico inverso in modo che l'esecuzione più recente venga 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 estraggono contenuto da Archiviazione di Azure: