Come indicizzare i dati di Cosmos DB usando un indicizzatore in Ricerca cognitiva di AzureHow to index Cosmos DB data using an indexer in Azure Cognitive Search

Importante

L'API SQL è disponibile a livello generale.SQL API is generally available. L'API MongoDB, l'API Gremlin e il supporto API Cassandra sono attualmente disponibili in anteprima pubblica.MongoDB API, Gremlin API, and Cassandra API support are currently in public preview. La funzionalità di anteprima viene fornita senza contratto di servizio e non è consigliata per i carichi di lavoro di produzione.Preview functionality is provided without a service level agreement, and is not recommended for production workloads. Per altre informazioni, vedere Condizioni supplementari per l'utilizzo delle anteprime di Microsoft Azure.For more information, see Supplemental Terms of Use for Microsoft Azure Previews. È possibile richiedere l'accesso alle anteprime compilando questo modulo.You can request access to the previews by filling out this form. Le versioni di anteprima dell'API REST forniscono queste funzionalità.REST API preview versions provide these features. Il supporto del portale è attualmente limitato e non è disponibile alcun supporto per .NET SDK.There is currently limited portal support, and no .NET SDK support.

Avviso

Solo Cosmos DB raccolte con criteri di indicizzazione impostati su coerente sono supportate da ricerca cognitiva di Azure.Only Cosmos DB collections with an indexing policy set to Consistent are supported by Azure Cognitive Search. L'indicizzazione di raccolte con criteri di indicizzazione differita non è consigliata e può comportare la mancanza di dati.Indexing collections with a Lazy indexing policy is not recommended and may result in missing data. Le raccolte con indicizzazione disabilitata non sono supportate.Collections with indexing disabled are not supported.

Questo articolo illustra come configurare un indicizzatore di Azure Cosmos DB per estrarre il contenuto e renderlo ricercabile in Azure ricerca cognitiva.This article shows you how to configure an Azure Cosmos DB indexer to extract content and make it searchable in Azure Cognitive Search. Questo flusso di lavoro crea un indice di ricerca cognitiva di Azure e lo carica con il testo esistente Estratto da Azure Cosmos DB.This workflow creates an Azure Cognitive Search index and loads it with existing text extracted from Azure Cosmos DB.

Poiché la terminologia può creare confusione, vale la pena notare che Azure Cosmos DB indicizzazione e l' indicizzazione di Azure ricerca cognitiva sono operazioni distinte, univoche per ogni servizio.Because terminology can be confusing, it's worth noting that Azure Cosmos DB indexing and Azure Cognitive Search indexing are distinct operations, unique to each service. Prima di avviare l'indicizzazione di Azure ricerca cognitiva, è necessario che il database di Azure Cosmos DB esista già e che contenga dati.Before you start Azure Cognitive Search indexing, your Azure Cosmos DB database must already exist and contain data.

L'indicizzatore Cosmos DB in Azure ricerca cognitiva può eseguire la ricerca per indicizzazione di Azure Cosmos DB elementi a cui si accede tramite protocolliThe Cosmos DB indexer in Azure Cognitive Search can crawl Azure Cosmos DB items accessed through different protocols.

Nota

È possibile eseguire il cast di un voto sulla voce dell'utente per la API tabella se si vuole visualizzarla come supportata in Azure ricerca cognitiva.You can cast a vote on User Voice for the Table API if you'd like to see it supported in Azure Cognitive Search.

Usare il portaleUse the portal

Nota

Il portale supporta attualmente l'API SQL e l'API MongoDB (anteprima).The portal currently supports the SQL API and MongoDB API (preview).

Il metodo più semplice per indicizzare gli elementi Azure Cosmos DB consiste nell'utilizzare una procedura guidata nel portale di Azure.The easiest method for indexing Azure Cosmos DB items is to use a wizard in the Azure portal. Eseguendo il campionamento dei dati e leggendo i metadati nel contenitore, la procedura guidata Importa dati in Azure ricerca cognitiva possibile creare un indice predefinito, eseguire il mapping dei campi di origine ai campi dell'indice di destinazione e caricare l'indice in un'unica operazione.By sampling data and reading metadata on the container, the Import data wizard in Azure Cognitive Search can create a default index, map source fields to target index fields, and load the index in a single operation. A seconda delle dimensioni e della complessità dei dati di origine, si può ottenere un indice di ricerca full-text operativo in pochi minuti.Depending on the size and complexity of source data, you could have an operational full text search index in minutes.

È consigliabile usare la stessa area o la stessa località sia per ricerca cognitiva di Azure che per Azure Cosmos DB per una latenza più bassa ed evitare costi di larghezza di banda.We recommend using the same region or location for both Azure Cognitive Search and Azure Cosmos DB for lower latency and to avoid bandwidth charges.

1 - Preparare i dati di origine1 - Prepare source data

È necessario avere un account Cosmos DB, un database Azure Cosmos DB mappato all'API SQL, l'API MongoDB (anteprima) o l'API Gremlin (anteprima) e il contenuto nel database.You should have a Cosmos DB account, an Azure Cosmos DB database mapped to the SQL API, MongoDB API (preview), or Gremlin API (preview), and content in the database.

Verificare che il database di Cosmos DB contenga dati.Make sure your Cosmos DB database contains data. La procedura guidata Importa dati legge i metadati ed esegue il campionamento dei dati per dedurre uno schema di indice, ma carica anche i dati da Cosmos DB.The Import data wizard reads metadata and performs data sampling to infer an index schema, but it also loads data from Cosmos DB. Se i dati risultano mancanti, la procedura guidata viene arrestata con l'errore "errore durante il rilevamento dello schema dell'indice dall'origine dati: Impossibile compilare un indice del prototipo perché DataSource ' emptycollection ' non ha restituito dati".If the data is missing, the wizard stops with this error "Error detecting index schema from data source: Could not build a prototype index because datasource 'emptycollection' returned no data".

2 - Avviare la procedura guidata Importa dati2 - Start Import data wizard

È possibile avviare la procedura guidata dalla barra dei comandi nella pagina del servizio ricerca cognitiva di Azure o, se ci si connette a Cosmos DB API SQL, è possibile fare clic su Aggiungi ricerca cognitiva di Azure nella sezione Impostazioni del riquadro di spostamento a sinistra dell'account di Cosmos DB.You can start the wizard from the command bar in the Azure Cognitive Search service page, or if you're connecting to Cosmos DB SQL API you can click Add Azure Cognitive Search in the Settings section of your Cosmos DB account's left navigation pane.

Comando Importa dati nel portaleImport data command in portal

3 - Impostare l'origine dati3 - Set the data source

Nella pagina origine dati , l'origine deve essere Cosmos DB, con le specifiche seguenti:In the data source page, the source must be Cosmos DB, with the following specifications:

  • Nome è il nome dell'oggetto origine dati.Name is the name of the data source object. Una volta creato, è possibile sceglierlo per altri carichi di lavoro.Once created, you can choose it for other workloads.

  • Cosmos DB account deve essere in uno dei formati seguenti:Cosmos DB account should be in one of the following formats:

    1. Stringa di connessione primaria o secondaria di Cosmos DB con il formato seguente: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>; .The primary or secondary connection string from Cosmos DB with the following format: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;.
      • Per la versione 3,2 e la versione 3,6 le raccolte MongoDB usano il formato seguente per l'account Cosmos DB nel portale di Azure: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;ApiKind=MongoDbFor version 3.2 and version 3.6 MongoDB collections use the following format for the Cosmos DB account in the Azure portal: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;ApiKind=MongoDb
      • Per i grafici Gremlin e le tabelle Cassandra, iscriversi all' anteprima dell'indicizzatore gestita per ottenere l'accesso all'anteprima e informazioni su come formattare le credenziali.For Gremlin graphs and Cassandra tables, sign up for the gated indexer preview to get access to the preview and information about how to format the credentials.
    2. Una stringa di connessione di identità gestita con il formato seguente che non include una chiave dell'account: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];) .A managed identity connection string with the following format that does not include an account key: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];). Per usare questo formato della stringa di connessione, seguire le istruzioni per la configurazione di una connessione dell'indicizzatore a un database di Cosmos DB usando un'identità gestita.To use this connection string format, follow the instructions for Setting up an indexer connection to a Cosmos DB database using a managed identity.
  • Il database è un database esistente dall'account.Database is an existing database from the account.

  • La raccolta è un contenitore di documenti.Collection is a container of documents. Per consentire l'importazione, è necessario che i documenti esistano.Documents must exist in order for import to succeed.

  • La query può essere vuota se si desiderano tutti i documenti. in caso contrario, è possibile immettere una query che seleziona un subset del documento.Query can be blank if you want all documents, otherwise you can input a query that selects a document subset. La query è disponibile solo per l'API SQL.Query is only available for the SQL API.

    Definizione dell'origine dati Cosmos DBCosmos DB data source definition

4-ignorare la pagina "arricchisci contenuto" della procedura guidata4 - Skip the "Enrich content" page in the wizard

L'aggiunta di competenze cognitive (o arricchimento) non è un requisito di importazione.Adding cognitive skills (or enrichment) is not an import requirement. A meno che non sia necessario aggiungere l' arricchimento di intelligenza artificiale alla pipeline di indicizzazione, è consigliabile ignorare questo passaggio.Unless you have a specific need to add AI enrichment to your indexing pipeline, you should skip this step.

Per ignorare il passaggio, fare clic sui pulsanti blu nella parte inferiore della pagina per "Avanti" e "Ignora".To skip the step, click the blue buttons at the bottom of the page for "Next" and "Skip".

5 - Impostare gli attributi dell'indice5 - Set index attributes

Nella pagina Indice dovrebbe essere presente un elenco di campi con un tipo di dati e una serie di caselle di controllo per l'impostazione degli attributi di indice.In the Index page, you should see a list of fields with a data type and a series of checkboxes for setting index attributes. La procedura guidata può generare un elenco di campi in base ai metadati e al campionamento dei dati di origine.The wizard can generate a fields list based on metadata and by sampling the source data.

È possibile selezionare in blocco gli attributi facendo clic sulla casella di controllo nella parte superiore di una colonna attributo.You can bulk-select attributes by clicking the checkbox at the top of an attribute column. Scegliere recuperabile e ricercabile per ogni campo che deve essere restituito a un'app client e soggetto all'elaborazione della ricerca full-text.Choose Retrievable and Searchable for every field that should be returned to a client app and subject to full text search processing. Si noterà che gli Integer non sono full-text o ricerca fuzzy (i numeri vengono valutati Verbatim e spesso sono utili nei filtri).You'll notice that integers are not full text or fuzzy searchable (numbers are evaluated verbatim and are often useful in filters).

Per ulteriori informazioni, vedere la descrizione degli attributi degli indici e degli analizzatori della lingua .Review the description of index attributes and language analyzers for more information.

Dedicare qualche momento alla revisione delle selezioni.Take a moment to review your selections. Con l'esecuzione della procedura guidata vengono create strutture dei dati fisiche e non è possibile eliminare questi campi senza eliminare e ricreare tutti gli oggetti.Once you run the wizard, physical data structures are created and you won't be able to edit these fields without dropping and recreating all objects.

Definizione dell'indice Cosmos DBCosmos DB index definition

6 - Creare l'indicizzatore6 - Create indexer

Nella sua specifica completa, la procedura guidata crea tre oggetti distinti nel servizio di ricerca.Fully specified, the wizard creates three distinct objects in your search service. Un oggetto origine dati e un oggetto indice vengono salvati come risorse denominate nel servizio ricerca cognitiva di Azure.A data source object and index object are saved as named resources in your Azure Cognitive Search service. L'ultimo passaggio crea un oggetto indicizzatore.The last step creates an indexer object. La denominazione dell'indicizzatore ne consente l'esistenza come risorsa autonoma, che può essere pianificata e gestita in modo indipendente dagli oggetti indice e origine dati, creati nella stessa sequenza della procedura guidata.Naming the indexer allows it to exist as a standalone resource, which you can schedule and manage independently of the index and data source object, created in the same wizard sequence.

Se non si ha familiarità con gli indicizzatori, un indicizzatore è una risorsa in Azure ricerca cognitiva che esegue la ricerca per indicizzazione di un'origine dati esterna per il contenuto ricercabile.If you are not familiar with indexers, an indexer is a resource in Azure Cognitive Search that crawls an external data source for searchable content. L'output della procedura guidata Importa dati è un indicizzatore che esegue la ricerca per indicizzazione dell'origine dati Cosmos DB, estrae contenuto ricercabile e lo importa in un indice in Azure ricerca cognitiva.The output of the Import data wizard is an indexer that crawls your Cosmos DB data source, extracts searchable content, and imports it into an index on Azure Cognitive Search.

La schermata seguente illustra la configurazione dell'indicizzatore predefinita.The following screenshot shows the default indexer configuration. È possibile passare a una sola volta se si desidera eseguire l'indicizzatore una sola volta.You can switch to Once if you want to run the indexer one time. Fare clic su Invia per eseguire la procedura guidata e creare tutti gli oggetti.Click Submit to run the wizard and create all objects. L'indicizzazione inizia immediatamente.Indexing commences immediately.

Definizione dell'indicizzatore Cosmos DBCosmos DB indexer definition

È possibile monitorare l'importazione dei dati nelle pagine del portale.You can monitor data import in the portal pages. Le notifiche di stato indicano lo stato dell'indicizzazione e il numero di documenti caricati.Progress notifications indicate indexing status and how many documents are uploaded.

Al termine dell'indicizzazione, è possibile usare Esplora ricerche per eseguire query sull'indice.When indexing is complete, you can use Search explorer to query your index.

Nota

Se non vengono visualizzati i dati previsti, potrebbe essere necessario impostare più attributi in altri campi.If you don't see the data you expect, you might need to set more attributes on more fields. Eliminare l'indice e l'indicizzatore appena creati, quindi eseguire di nuovo la procedura guidata modificando le selezioni per gli attributi di indice nel passaggio 5.Delete the index and indexer you just created, and step through the wizard again, modifying your selections for index attributes in step 5.

Usare le API RESTUse REST APIs

È possibile usare l'API REST per indicizzare i dati Azure Cosmos DB, seguendo un flusso di lavoro in tre parti comune a tutti gli indicizzatori in Azure ricerca cognitiva: creare un'origine dati, creare un indice, creare un indicizzatore.You can use the REST API to index Azure Cosmos DB data, following a three-part workflow common to all indexers in Azure Cognitive Search: create a data source, create an index, create an indexer. L'estrazione dei dati da Cosmos DB si verifica quando si invia la richiesta create Indexer.Data extraction from Cosmos DB occurs when you submit the Create Indexer request. Al termine di questa richiesta, sarà presente un indice Queryable.After this request is finished, you will have a queryable index.

Nota

Per l'indicizzazione dei dati da Cosmos DB API Gremlin o Cosmos DB API Cassandra è necessario prima di tutto richiedere l'accesso alle anteprime gestite compilando questo modulo.For indexing data from Cosmos DB Gremlin API or Cosmos DB Cassandra API you must first request access to the gated previews by filling out this form. Al termine dell'elaborazione della richiesta, si riceveranno istruzioni su come usare l' API REST versione 2020-06-30-Preview per creare l'origine dati.Once your request is processed, you will receive instructions for how to use the REST API version 2020-06-30-Preview to create the data source.

In precedenza in questo articolo si è indicato che Azure Cosmos DB indicizzazione e l'indicizzazione di Azure ricerca cognitiva Indexing sono operazioni distinte.Earlier in this article it is mentioned that Azure Cosmos DB indexing and Azure Cognitive Search indexing indexing are distinct operations. Per l'indicizzazione Cosmos DB, per impostazione predefinita tutti i documenti vengono indicizzati automaticamente tranne che con il API Cassandra.For Cosmos DB indexing, by default all documents are automatically indexed except with the Cassandra API. Se si disattiva l'indicizzazione automatica, è possibile accedere ai documenti solo tramite i relativi collegamenti automatici o tramite query usando l'ID del documento.If you turn off automatic indexing, documents can be accessed only through their self-links or by queries by using the document ID. L'indicizzazione di Azure ricerca cognitiva richiede l'abilitazione dell'indicizzazione automatica Cosmos DB nella raccolta che verrà indicizzata da Azure ricerca cognitiva.Azure Cognitive Search indexing requires Cosmos DB automatic indexing to be turned on in the collection that will be indexed by Azure Cognitive Search. Quando si effettua l'iscrizione per l'anteprima di Cosmos DB API Cassandra indexer, verranno fornite istruzioni su come configurare Cosmos DB l'indicizzazione.When signing up for the Cosmos DB Cassandra API indexer preview, you'll be given instructions on how set up Cosmos DB indexing.

Avviso

Azure Cosmos DB è la nuova generazione di DocumentDB.Azure Cosmos DB is the next generation of DocumentDB. In precedenza con l'API versione 2017-11-11 è possibile usare la documentdb sintassi.Previously with API version 2017-11-11 you could use the documentdb syntax. Ciò significava che è possibile specificare il tipo di origine dati come cosmosdb o documentdb .This meant that you could specify your data source type as cosmosdb or documentdb. A partire dalla versione API 2019-05-06 , le API e il portale di Azure ricerca cognitiva supportano solo la cosmosdb sintassi come indicato in questo articolo.Starting with API version 2019-05-06 both the Azure Cognitive Search APIs and Portal only support the cosmosdb syntax as instructed in this article. Questo significa che il tipo di origine dati deve essere cosmosdb connesso a un endpoint Cosmos DB.This means that the data source type must cosmosdb if you would like to connect to a Cosmos DB endpoint.

1-assemblare gli input per la richiesta1 - Assemble inputs for the request

Per ogni richiesta, è necessario fornire il nome del servizio e la chiave amministratore per Azure ricerca cognitiva (nell'intestazione POST) e il nome e la chiave dell'account di archiviazione per l'archiviazione BLOB.For each request, you must provide the service name and admin key for Azure Cognitive Search (in the POST header), and the storage account name and key for blob storage. Per inviare richieste HTTP ad Azure ricerca cognitiva, è possibile usare il post o il Visual Studio Code .You can use Postman or Visual Studio Code to send HTTP requests to Azure Cognitive Search.

Copiare i quattro valori seguenti nel blocco note in modo che sia possibile incollarli in una richiesta:Copy the following four values into Notepad so that you can paste them into a request:

  • Nome del servizio ricerca cognitiva di AzureAzure Cognitive Search service name
  • Chiave amministratore di Azure ricerca cognitivaAzure Cognitive Search admin key
  • Stringa di connessione Cosmos DBCosmos DB connection string

È possibile trovare questi valori nel portale:You can find these values in the portal:

  1. Nelle pagine del portale per ricerca cognitiva di Azure copiare l'URL del servizio di ricerca dalla pagina panoramica.In the portal pages for Azure Cognitive Search, copy the search service URL from the Overview page.

  2. Nel riquadro di spostamento a sinistra fare clic su chiavi e quindi copiare la chiave primaria o secondaria (sono equivalenti).In the left navigation pane, click Keys and then copy either the primary or secondary key (they are equivalent).

  3. Passare alle pagine del portale per l'account di archiviazione Cosmos.Switch to the portal pages for your Cosmos storage account. Nel riquadro di spostamento a sinistra, in Impostazioni, fare clic su chiavi.In the left navigation pane, under Settings, click Keys. Questa pagina fornisce un URI, due set di stringhe di connessione e due set di chiavi.This page provides a URI, two sets of connection strings, and two sets of keys. Copiare una delle stringhe di connessione nel blocco note.Copy one of the connection strings to Notepad.

2-creare un'origine dati2 - Create a data source

Un'origine dati specifica i dati per l'indice, le credenziali e i criteri per l'identificazione delle modifiche apportate ai dati (ad esempio documenti modificati o eliminati nella raccolta).A data source specifies the data to index, credentials, and policies for identifying changes in the data (such as modified or deleted documents inside your collection). L'origine dati è definita come risorsa indipendente affinché possa essere usata da più indicizzatori.The data source is defined as an independent resource so that it can be used by multiple indexers.

Per creare un'origine dati, formulare una richiesta POST:To create a data source, formulate a POST request:


    POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
    Content-Type: application/json
    api-key: [Search service admin key]

    {
        "name": "mycosmosdbdatasource",
        "type": "cosmosdb",
        "credentials": {
            "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
        },
        "container": { "name": "myCollection", "query": null },
        "dataChangeDetectionPolicy": {
            "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName": "_ts"
        }
    }

Il corpo della richiesta contiene la definizione dell'origine dati, che deve includere i campi seguenti:The body of the request contains the data source definition, which should include the following fields:

CampoField DescrizioneDescription
nomename Obbligatorio.Required. Scegliere un nome qualsiasi per rappresentare l’oggetto origine dati.Choose any name to represent your data source object.
typetype Obbligatorio.Required. Deve essere cosmosdb.Must be cosmosdb.
credentialscredentials Obbligatorio.Required. Deve seguire il formato della stringa di connessione Cosmos DB o un formato della stringa di connessione identità gestita.Must either follow the Cosmos DB connection string format or a managed identity connection string format.

Per le raccolte SQL, le stringhe di connessione possono seguire uno dei formati seguenti:For SQL collections, connection strings can follow either of the below formats:
  • AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>
  • Una stringa di connessione di identità gestita con il formato seguente che non include una chiave dell'account: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/; .A managed identity connection string with the following format that does not include an account key: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;. Per usare questo formato della stringa di connessione, seguire le istruzioni per la configurazione di una connessione dell'indicizzatore a un database di Cosmos DB usando un'identità gestita.To use this connection string format, follow the instructions for Setting up an indexer connection to a Cosmos DB database using a managed identity.

    Per la versione 3,2 e la versione 3,6 le raccolte MongoDB utilizzano uno dei formati seguenti per la stringa di connessione:For version 3.2 and version 3.6 MongoDB collections use either of the following formats for the connection string:
  • AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb
  • Una stringa di connessione di identità gestita con il formato seguente che non include una chiave dell'account: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;ApiKind=MongoDb; .A managed identity connection string with the following format that does not include an account key: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;ApiKind=MongoDb;. Per usare questo formato della stringa di connessione, seguire le istruzioni per la configurazione di una connessione dell'indicizzatore a un database di Cosmos DB usando un'identità gestita.To use this connection string format, follow the instructions for Setting up an indexer connection to a Cosmos DB database using a managed identity.

    Per i grafici Gremlin e le tabelle Cassandra, iscriversi all' anteprima dell'indicizzatore gestita per ottenere l'accesso all'anteprima e informazioni su come formattare le credenziali.For Gremlin graphs and Cassandra tables, sign up for the gated indexer preview to get access to the preview and information about how to format the credentials.

    Evitare i numeri di porta nell'URL dell'endpoint.Avoid port numbers in the endpoint url. Se si include il numero di porta, Azure ricerca cognitiva non sarà in grado di indicizzare il database Azure Cosmos DB.If you include the port number, Azure Cognitive Search will be unable to index your Azure Cosmos DB database.
  • containercontainer Contiene gli elementi seguenti:Contains the following elements:
    name: Obbligatorio.name: Required. Specificare l'ID della raccolta di database da indicizzare.Specify the ID of the database collection to be indexed.
    query: Facoltativa.query: Optional. È possibile specificare una query per rendere flat un documento JSON arbitrario in modo da ottenere uno schema flat che possa essere indicizzato da Ricerca cognitiva di Azure.You can specify a query to flatten an arbitrary JSON document into a flat schema that Azure Cognitive Search can index.
    Per le API MongoDB, Gremlin e Apache Cassandra, le query non sono supportate.For the MongoDB API, Gremlin API, and Cassandra API, queries are not supported.
    dataChangeDetectionPolicydataChangeDetectionPolicy Consigliato.Recommended. Vedere la sezione Indicizzazione di documenti modificati.See Indexing Changed Documents section.
    dataDeletionDetectionPolicydataDeletionDetectionPolicy facoltativo.Optional. Vedere la sezione Indicizzazione di documenti eliminati.See Indexing Deleted Documents section.

    Utilizzo di query per formare dati indicizzatiUsing queries to shape indexed data

    È possibile specificare una query di SQL per appiattire le matrici o le proprietà annidate, progettare le proprietà JSON e filtrare i dati da indicizzare.You can specify a SQL query to flatten nested properties or arrays, project JSON properties, and filter the data to be indexed.

    Avviso

    Le query personalizzate non sono supportate per l' API MongoDB, l' api Gremlin e API Cassandra: il container.query parametro deve essere impostato su null o omesso.Custom queries are not supported for MongoDB API, Gremlin API, and Cassandra API: container.query parameter must be set to null or omitted. Se è necessario usare una query personalizzata, inviare un messaggio su User Voice.If you need to use a custom query, please let us know on User Voice.

    Documento di esempio:Example document:

        {
            "userId": 10001,
            "contact": {
                "firstName": "andy",
                "lastName": "hoh"
            },
            "company": "microsoft",
            "tags": ["azure", "cosmosdb", "search"]
        }
    

    Query di filtro:Filter query:

    SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts
    

    Query di appiattimento:Flattening query:

    SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts
    

    Query di proiezione:Projection query:

    SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts
    

    Query di appiattimento matrici:Array flattening query:

    SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts
    

    3: creare un indice di ricerca di destinazione3 - Create a target search index

    Creare un indice di ricerca cognitiva di Azure di destinazione se non ne è già presente uno.Create a target Azure Cognitive Search index if you don’t have one already. Nell'esempio seguente viene creato un indice con un campo ID e Descrizione:The following example creates an index with an ID and description field:

        POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
        Content-Type: application/json
        api-key: [Search service admin key]
    
        {
           "name": "mysearchindex",
           "fields": [{
             "name": "id",
             "type": "Edm.String",
             "key": true,
             "searchable": false
           }, {
             "name": "description",
             "type": "Edm.String",
             "filterable": false,
             "sortable": false,
             "facetable": false,
             "suggestions": true
           }]
         }
    

    Assicurarsi che lo schema dell'indice di destinazione sia compatibile con lo schema dei documenti JSON di origine oppure con l'output della proiezione di query personalizzata.Ensure that the schema of your target index is compatible with the schema of the source JSON documents or the output of your custom query projection.

    Nota

    Per le raccolte partizionate, la chiave del documento predefinita è Azure Cosmos DB _rid proprietà, a cui Azure ricerca cognitiva automaticamente rinominare rid perché i nomi dei campi non possono iniziare con un carattere di sottolineatura.For partitioned collections, the default document key is Azure Cosmos DB's _rid property, which Azure Cognitive Search automatically renames to rid because field names cannot start with an underscore character. Inoltre, _rid i valori Azure Cosmos DB contengono caratteri non validi nelle chiavi di ricerca cognitiva di Azure.Also, Azure Cosmos DB _rid values contain characters that are invalid in Azure Cognitive Search keys. Per questo motivo, i valori _rid presentano la codificata Base64.For this reason, the _rid values are Base64 encoded.

    Per le raccolte MongoDB, Azure ricerca cognitiva Rinomina automaticamente la _id Proprietà in id .For MongoDB collections, Azure Cognitive Search automatically renames the _id property to id.

    Mapping tra tipi di dati JSON e tipi di dati ricerca cognitiva di AzureMapping between JSON Data Types and Azure Cognitive Search Data Types

    Tipo di dati JSONJSON data type Tipi di campi dell'indice di destinazione compatibiliCompatible target index field types
    BoolBool Edm.Boolean, Edm.StringEdm.Boolean, Edm.String
    Numeri che rappresentano numeri interiNumbers that look like integers Edm.Int32, Edm.Int64, Edm.StringEdm.Int32, Edm.Int64, Edm.String
    Numeri che rappresentano numeri a virgola mobileNumbers that look like floating-points Edm.Double, Edm.StringEdm.Double, Edm.String
    stringString Edm.StringEdm.String
    Matrici di tipi primitivi, ad esempio ["a", "b", "c"]Arrays of primitive types, for example ["a", "b", "c"] Collection(Edm.String)Collection(Edm.String)
    Stringhe che rappresentano dateStrings that look like dates Edm.DateTimeOffset, Edm.StringEdm.DateTimeOffset, Edm.String
    Oggetti GeoJSON, ad esempio { "type": "Point", "coordinates": [long, lat] }GeoJSON objects, for example { "type": "Point", "coordinates": [long, lat] } Edm.GeographyPointEdm.GeographyPoint
    Altri oggetti JSONOther JSON objects N/DN/A

    4-configurare ed eseguire l'indicizzatore4 - Configure and run the indexer

    Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore:Once the index and data source have been created, you're ready to create the indexer:

        POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
        Content-Type: application/json
        api-key: [admin key]
    
        {
          "name" : "mycosmosdbindexer",
          "dataSourceName" : "mycosmosdbdatasource",
          "targetIndexName" : "mysearchindex",
          "schedule" : { "interval" : "PT2H" }
        }
    

    L'indicizzatore verrà eseguito ogni due ore (l'intervallo di pianificazione è impostato su "PT2H").This indexer runs every two hours (schedule interval is set to "PT2H"). Per eseguire un indicizzatore ogni 30 minuti, impostare l'intervallo su "PT30M".To run an indexer every 30 minutes, set the interval to "PT30M". L'intervallo minimo supportato è di 5 minuti.The shortest supported interval is 5 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 di un indicizzatore, vedere Creare un indicizzatore.For more details on the Create Indexer API, check out Create Indexer.

    Per ulteriori informazioni sulla definizione delle pianificazioni degli indicizzatori, vedere How to Schedule Indexers for Azure ricerca cognitiva.For more information about defining indexer schedules, see How to schedule indexers for Azure Cognitive Search.

    Usare .NETUse .NET

    .NET SDK disponibile a livello generale ha una parità completa con l'API REST disponibile a livello generale.The generally available .NET SDK has full parity with the generally available REST API. È consigliabile rivedere la sezione relativa dall'API REST per apprenderne i concetti, il flusso di lavoro e i requisiti.We recommend that you review the previous REST API section to learn concepts, workflow, and requirements. Consultare quindi la seguente documentazione di riferimento sull'API .NET per implementare un indicizzatore JSON nel codice gestito.You can then refer to following .NET API reference documentation to implement a JSON indexer in managed code.

    Indicizzazione di documenti modificatiIndexing changed documents

    Lo scopo di un criterio di rilevamento delle modifiche dei dati è quello di identificare in modo efficace gli elementi di dati modificati.The purpose of a data change detection policy is to efficiently identify changed data items. Attualmente, l'unico criterio supportato è l' HighWaterMarkChangeDetectionPolicy utilizzo della _ts Proprietà (timestamp) fornita da Azure Cosmos DB, specificata come indicato di seguito:Currently, the only supported policy is the HighWaterMarkChangeDetectionPolicy using the _ts (timestamp) property provided by Azure Cosmos DB, which is specified as follows:

        {
            "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName" : "_ts"
        }
    

    L'uso di questi criteri è consigliato per garantire elevate prestazioni dell'indicizzatore.Using this policy is highly recommended to ensure good indexer performance.

    Se si usa una query personalizzata, assicurarsi che la proprietà _ts sia progettata dalla query.If you are using a custom query, make sure that the _ts property is projected by the query.

    Avanzamento incrementale e query personalizzateIncremental progress and custom queries

    L'avanzamento incrementale durante l'indicizzazione assicura che, in caso di interruzione dell'esecuzione dell'indicizzatore a causa di errori temporanei o del limite del tempo di esecuzione, l'indicizzatore possa riprendere dal punto in cui è stato interrotto all'esecuzione successiva, invece di dovere ripetere dall'inizio l'indicizzazione dell'intera raccolta.Incremental progress during indexing ensures that if indexer execution is interrupted by transient failures or execution time limit, the indexer can pick up where it left off next time it runs, instead of having to reindex the entire collection from scratch. Questo approccio risulta particolarmente importante in caso di indicizzazione di raccolte di grandi dimensioni.This is especially important when indexing large collections.

    Per abilitare l'avanzamento incrementale quando si usa una query personalizzata, assicurarsi che la query ordini i risultati in base alla colonna _ts.To enable incremental progress when using a custom query, ensure that your query orders the results by the _ts column. In questo modo viene abilitato il controllo periodico che Azure ricerca cognitiva USA per fornire lo stato di avanzamento incrementale in presenza di errori.This enables periodic check-pointing that Azure Cognitive Search uses to provide incremental progress in the presence of failures.

    In alcuni casi, anche se la query contiene una ORDER BY [collection alias]._ts clausola, Azure ricerca cognitiva potrebbe non dedurre che la query è ordinata in base a _ts .In some cases, even if your query contains an ORDER BY [collection alias]._ts clause, Azure Cognitive Search may not infer that the query is ordered by the _ts. È possibile indicare ad Azure ricerca cognitiva che i risultati vengono ordinati usando la assumeOrderByHighWaterMarkColumn proprietà di configurazione.You can tell Azure Cognitive Search that results are ordered by using the assumeOrderByHighWaterMarkColumn configuration property. Per specificare questo hint, creare o aggiornare l'indicizzatore come indicato di seguito:To specify this hint, create or update your indexer as follows:

        {
         ... other indexer definition properties
         "parameters" : {
                "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
        } 
    

    Indicizzazione di documenti eliminatiIndexing deleted documents

    Quando si eliminano righe dalla raccolta, in genere le si elimina anche dall'indice di ricerca.When rows are deleted from the collection, you normally want to delete those rows from the search index as well. Scopo dei criteri di rilevamento dell'eliminazione dei dati è quello di identificare in modo efficace gli elementi di dati eliminati.The purpose of a data deletion detection policy is to efficiently identify deleted data items. Attualmente, l'unico criterio supportato è il criterio Soft Delete (l'eliminazione è contrassegnata da un tipo di flag), specificato come indicato sotto:Currently, the only supported policy is the Soft Delete policy (deletion is marked with a flag of some sort), which is specified as follows:

        {
            "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
            "softDeleteColumnName" : "the property that specifies whether a document was deleted",
            "softDeleteMarkerValue" : "the value that identifies a document as deleted"
        }
    

    Se si usa una query personalizzata, assicurarsi che la proprietà a cui fa riferimento softDeleteColumnName sia progettata dalla query.If you are using a custom query, make sure that the property referenced by softDeleteColumnName is projected by the query.

    L'esempio seguente crea un'origine dati con criteri di eliminazione temporanea:The following example creates a data source with a soft-deletion policy:

        POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
        Content-Type: application/json
        api-key: [Search service admin key]
    
        {
            "name": "mycosmosdbdatasource",
            "type": "cosmosdb",
            "credentials": {
                "connectionString": "AccountEndpoint=https://myCosmosDbEndpoint.documents.azure.com;AccountKey=myCosmosDbAuthKey;Database=myCosmosDbDatabaseId"
            },
            "container": { "name": "myCosmosDbCollectionId" },
            "dataChangeDetectionPolicy": {
                "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
                "highWaterMarkColumnName": "_ts"
            },
            "dataDeletionDetectionPolicy": {
                "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
                "softDeleteColumnName": "isDeleted",
                "softDeleteMarkerValue": "true"
            }
        }
    

    Passaggi successiviNext steps

    La procedura è stata completata.Congratulations! Si è appreso come integrare Azure Cosmos DB con ricerca cognitiva di Azure usando un indicizzatore.You have learned how to integrate Azure Cosmos DB with Azure Cognitive Search using an indexer.