Indicizzare in Archiviazione tabelle di Azure con Ricerca di AzureIndex Azure Table storage with Azure Search

In questo articolo viene illustrato come usare Ricerca di Azure per indicizzare i dati archiviati in Archiviazione tabelle di Azure.This article shows how to use Azure Search to index data stored in Azure Table storage.

Configurare l'indicizzazione in Archiviazione tabelle di AzureSet up Azure Table storage indexing

È possibile configurare un indicizzatore dell'Archiviazione tabelle di Azure mediante queste risorse:You can set up an Azure Table storage indexer by using these resources:

In questo caso viene illustrato il flusso tramite l'API REST.Here we demonstrate the flow by using the REST API.

Passaggio 1: Creare un'origine datiStep 1: Create a datasource

Un'origine dati specifica i dati da indicizzare, le credenziali necessarie per accedere ai dati e le norme che consentono a Ricerca di Azure di identificare in modo efficace le modifiche apportate ai dati.A datasource specifies which data to index, the credentials needed to access the data, and the policies that enable Azure Search to efficiently identify changes in the data.

Per l'indicizzazione delle tabelle, l'origine dati deve possedere le proprietà seguenti:For table indexing, the datasource must have the following properties:

  • Il parametro name è il nome univoco dell'origine dati all'interno del servizio di ricerca.name is the unique name of the datasource within your search service.
  • type deve essere azuretable.type must be azuretable.
  • Il parametro credentials contiene la stringa di connessione all'account di archiviazione.credentials parameter contains the storage account connection string. Per altre informazioni, vedere Specificare le credenziali.See the Specify credentials section for details.
  • Il parametro container imposta il nome della tabella e una query facoltativa.container sets the table name and an optional query.
    • Specificare il nome della tabella usando il parametro name.Specify the table name by using the name parameter.
    • Specificare facoltativamente una query usando il parametro query.Optionally, specify a query by using the query parameter.

Importante

Se possibile, usare un filtro sul parametro PartitionKey per ottimizzare le prestazioni.Whenever possible, use a filter on PartitionKey for better performance. Qualsiasi altra query comporterà un'analisi completa delle tabelle e un conseguente peggioramento delle prestazioni in caso di tabelle di grandi dimensioni.Any other query does a full table scan, resulting in poor performance for large tables. Vedere Considerazioni sulle prestazioni.See the Performance considerations section.

Per creare un'origine dati:To create a datasource:

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

{
    "name" : "table-datasource",
    "type" : "azuretable",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-table", "query" : "PartitionKey eq '123'" }
}   

Per altre informazioni sull'API di creazione dell'origine dati, vedere Creare un'origine dati.For more information on the Create Datasource API, see Create Datasource.

Metodi per specificare le credenzialiWays to specify credentials

Per specificare le credenziali per la tabella, sono disponibili questi modi:You can provide the credentials for the table in one of these ways:

  • Stringa di connessione dell'account di archiviazione per accesso completo: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>.Per ottenere la stringa di connessione dal portale di Azure, passare al pannello dell'account di archiviazione e quindi selezionare > Impostazioni > Chiavi (per gli account di archiviazione della versione classica) oppure Impostazioni > Chiavi di accesso (per gli account di archiviazione di Azure Resource Manager).Full access storage account connection string: DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key> You can get the connection string from the Azure portal by going to the Storage account blade > Settings > Keys (for classic storage accounts) or Settings > Access keys (for Azure Resource Manager storage accounts).
  • Stringa di connessione della firma di accesso condiviso dell'account di archiviazione: TableEndpoint=https://<your account>.table.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl la firma di accesso condiviso deve avere le autorizzazioni per le operazioni di elenco e lettura per i contenitori (tabelle) e gli oggetti (righe di tabella).Storage account shared access signature connection string: TableEndpoint=https://<your account>.table.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=t&sp=rl The shared access signature should have the list and read permissions on containers (tables in this case) and objects (table rows).
  • Firma di accesso condiviso tabella: ContainerSharedAccessUri=https://<your storage account>.table.core.windows.net/<table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r la firma di accesso condiviso deve disporre delle autorizzazioni di query (lettura) nella tabella.Table shared access signature: ContainerSharedAccessUri=https://<your storage account>.table.core.windows.net/<table name>?tn=<table name>&sv=2016-05-31&sig=<the signature>&se=<the validity end time>&sp=r The shared access signature should have query (read) permissions on the table.

Per altre informazioni sulle firme di accesso condiviso, vedere Uso delle firme di accesso condiviso.For more information on storage shared access signatures, see Using shared access signatures.

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.If you use shared access signature credentials, you will need to update the datasource credentials periodically with renewed signatures to prevent their expiration. Se le credenziali di firma di accesso condiviso scadono, l'indicizzatore ha esito negativo con un messaggio di errore simile a "Le credenziali specificate nella stringa di connessione non sono valide o sono scadute".If shared access signature credentials expire, the indexer fails with an error message similar to "Credentials provided in the connection string are invalid or have expired."

Passaggio 2: Creare un indiceStep 2: Create an index

L'indice consente di specificare i campi in un documento, gli attributi e altri costrutti che danno forma all'esperienza della ricerca.The index specifies the fields in a document, the attributes, and other constructs that shape the search experience.

Per creare un indice:To create an index:

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

{
      "name" : "my-target-index",
      "fields": [
        { "name": "key", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true }
      ]
}

Per altre informazioni sulla creazione di indici, vedere Creare un indice.For more information on creating indexes, see Create Index.

Passaggio 3: Creare un indicizzatoreStep 3: Create an indexer

Un indicizzatore si connette a un'origine dati con un indice di ricerca di destinazione e consente di pianificare l'automatizzazione dell'aggiornamento dei dati.An indexer connects a datasource with a target search index and provides a schedule to automate the data refresh.

Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore:After the index and datasource are created, you're ready to create the indexer:

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

{
  "name" : "table-indexer",
  "dataSourceName" : "table-datasource",
  "targetIndexName" : "my-target-index",
  "schedule" : { "interval" : "PT2H" }
}

L'indicizzatore verrà eseguito ogni due ore.This indexer runs every two hours. L'intervallo di pianificazione è impostato su "PT2H". Per eseguire un indicizzatore ogni 30 minuti, impostare l'intervallo su "PT30M".(The schedule interval is set to "PT2H".) To run an indexer every 30 minutes, set the interval to "PT30M". L'intervallo minimo supportato è di cinque minuti.The shortest supported interval is five minutes. La pianificazione è facoltativa; se omessa, l'indicizzatore viene eseguito una sola volta al momento della creazione.The schedule is optional; if omitted, an indexer runs only once when it's created. Tuttavia, è possibile eseguire un indicizzatore su richiesta in qualsiasi momento.However, you can run an indexer on demand at any time.

Per altre informazioni sull'API di creazione dell'indicizzatore dati, vedere Creare un indicizzatore.For more information on the Create Indexer API, see Create Indexer.

Gestire nomi campo diversiDeal with different field names

I nomi campo nell'indice esistente sono talvolta diversi dai nomi proprietà nella tabella.Sometimes, the field names in your existing index are different from the property names in your table. È possibile usare i mapping dei campi per eseguire il mapping dei nomi di proprietà forniti dalla tabella ai nomi di campo nell'indice di ricerca.You can use field mappings to map the property names from the table to the field names in your search index. Per altre informazioni sui mapping dei campi, vedere I mapping dei campi dell'indicizzatore di Ricerca di Azure colmano le differenze tra le origini dati e gli indici di ricerca.To learn more about field mappings, see Azure Search indexer field mappings bridge the differences between datasources and search indexes.

Gestire le chiavi del documentoHandle document keys

In Ricerca di Azure la chiave del documento identifica un documento in modo univoco.In Azure Search, the document key uniquely identifies a document. Ogni indice di ricerca deve avere esclusivamente un campo chiave di tipo Edm.String.Every search index must have exactly one key field of type Edm.String. Il campo chiave è necessario per ogni documento da aggiungere all'indice.The key field is required for each document that is being added to the index. È l'unico campo obbligatorio.(In fact, it's the only required field.)

La chiave delle righe è composta. Ricerca di Azure genera pertanto un campo sintetico denominato Key, vale a dire una concatenazione di valori di chiave di partizione e chiave di riga.Because table rows have a compound key, Azure Search generates a synthetic field called Key that is a concatenation of partition key and row key values. Se ad esempio il parametro PartitionKey di una riga è PK1 e il parametro RowKey è RK1, il valore del campo Key è PK1RK1.For example, if a row’s PartitionKey is PK1 and RowKey is RK1, then the Key field's value is PK1RK1.

Nota

Il valore Key può contenere caratteri non validi nelle chiavi del documento, ad esempio i trattini.The Key value may contain characters that are invalid in document keys, such as dashes. È possibile risolvere i problemi legati ai caratteri non validi usando la base64Encode funzione di mapping dei campi.You can deal with invalid characters by using the base64Encode field mapping function. In questo caso, ricordarsi di usare la codifica Base64 sicura per gli URL quando si passano le chiavi dei documenti nelle chiamate API, ad esempio in una ricerca.If you do this, remember to also use URL-safe Base64 encoding when passing document keys in API calls such as Lookup.

Indicizzazione incrementale e rilevamento delle eliminazioniIncremental indexing and deletion detection

Quando un indicizzatore di tabelle viene configurato per l'esecuzione in base a una pianificazione, vengono indicizzate nuovamente solo le righe nuove o aggiornate, come definito dal valore Timestamp di una riga.When you set up a table indexer to run on a schedule, it reindexes only new or updated rows, as determined by a row’s Timestamp value. Non è necessario specificare una norma di rilevamento delle modifiche.You don’t have to specify a change detection policy. L'indicizzazione incrementale viene abilitata automaticamente.Incremental indexing is enabled for you automatically.

Per indicare che alcuni documenti specifici devono essere rimossi dall'indice, è possibile usare una strategia di eliminazione temporanea.To indicate that certain documents must be removed from the index, you can use a soft delete strategy. Invece di eliminare una riga, aggiungere una proprietà che ne indica l'eliminazione e impostare norme di rilevamento dell'eliminazione temporanea nell'origine dati.Instead of deleting a row, add a property to indicate that it's deleted, and set up a soft deletion detection policy on the datasource. Il tipo di norme seguente, ad esempio, indica che una riga viene eliminata se la proprietà IsDeleted della riga è impostata sul valore "true":For example, the following policy considers that a row is deleted if the row has a property IsDeleted with the value "true":

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

{
    "name" : "my-table-datasource",
    "type" : "azuretable",
    "credentials" : { "connectionString" : "<your storage connection string>" },
    "container" : { "name" : "table name", "query" : "<query>" },
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }
}   

Considerazioni sulle prestazioniPerformance considerations

Ricerca di Azure usa per impostazione predefinita il filtro di query seguente: Timestamp >= HighWaterMarkValue.By default, Azure Search uses the following query filter: 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.Because Azure tables don’t have a secondary index on the Timestamp field, this type of query requires a full table scan and is therefore slow for large tables.

Ecco due possibili approcci per migliorare le prestazioni dell'indicizzazione delle tabelle.Here are two possible approaches for improving table indexing performance. Entrambi gli approcci si basano sull'utilizzo delle partizioni delle tabelle:Both of these approaches rely on using table partitions:

  • 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.If your data can naturally be partitioned into several partition ranges, create a datasource and a corresponding indexer for each partition range. Ogni indicizzatore deve a questo punto elaborare un solo intervallo specifico della partizione e ciò va a vantaggio delle prestazioni della query.Each indexer now has to process only a specific partition range, resulting in better query performance. Se i dati da indicizzare hanno un numero ridotto di partizioni fisse, è ancora meglio, perché ciascun indicizzatore analizza solo una partizione.If the data that needs to be indexed has a small number of fixed partitions, even better: each indexer only does a partition scan. 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:For example, to create a datasource for processing a partition range with keys from 000 to 100, use a query like this:

    "container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }
    
  • Se i dati sono partizionati in base all'ora (ad esempio, si crea una nuova partizione ogni giorno o ogni settimana), considerare l'approccio seguente:If your data is partitioned by time (for example, you create a new partition every day or week), consider the following approach:

    • Usare una query nel formato: (PartitionKey ge <TimeStamp>) and (other filters).Use a query of the form: (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.Monitor indexer progress by using Get Indexer Status API, and periodically update the <TimeStamp> condition of the query based on the latest successful high-water-mark value.
    • Con questo approccio, se è necessario attivare una reindicizzazione completa, occorre reimpostare la query dell'origine dati oltre a reimpostare l'indicizzatore.With this approach, if you need to trigger a complete reindexing, you need to reset the datasource query in addition to resetting the indexer.

Come contribuire al miglioramento di Ricerca di AzureHelp us make Azure Search better

Se si hanno domande sulle funzionalità o idee per apportare miglioramenti, contattare Microsoft sul sito UserVoice.If you have feature requests or ideas for improvements, submit them on our UserVoice site.