Gegevens uit Azure Cosmos DB indexeren met behulp SQL of MongoDB-API's

In dit artikel wordt beschreven hoe u een indexeringsfunctie Azure Cosmos DB om inhoud te extraheren en deze doorzoekbaar te maken in Azure Cognitive Search. Deze werkstroom maakt een Azure Cognitive Search index en laadt deze met bestaande tekst die is geëxtraheerd uit Azure Cosmos DB.

Omdat terminologie verwarrend kan zijn, is het de moeite waard om te weten dat Azure Cosmos DB indexering en Azure Cognitive Search indexering afzonderlijke bewerkingen zijn, die uniek zijn voor elke service. Voordat u begint met Azure Cognitive Search indexeren, moet Azure Cosmos DB database al bestaan en gegevens bevatten.

De Cosmos DB indexer in Azure Cognitive Search kunt Azure Cosmos DB items die via de volgende protocollen worden gebruikt, crawlen.

• Voor SQL API, die algemeen beschikbaar is, kunt u de portal, REST API, .NET SDKof een andere Azure SDK gebruiken om de gegevensbron en indexer te maken.

• Voor mongoDB-API (preview)kunt u de portal of de REST API-versie 2020-06-30-Preview gebruiken om de gegevensbron en indexer te maken.

Vereisten

Alleen Cosmos DB verzamelingen met een indexeringsbeleid ingesteld op Consistent worden ondersteund door Azure Cognitive Search. Het indexeren van verzamelingen met een lui indexeringsbeleid wordt niet aanbevolen en kan leiden tot ontbrekende gegevens. Verzamelingen met uitgeschakelde indexering worden niet ondersteund.

Gebruik de portal

De eenvoudigste methode voor het indexeren van Azure Cosmos DB items is het gebruik van een wizard in Azure Portal. Door steekproeven te nemen van gegevens en metagegevens te lezen in de container, kan de wizard Gegevens importeren in Azure Cognitive Search een standaardindex maken, bronvelden aan doelindexvelden toe te voegen en de index in één bewerking laden. Afhankelijk van de grootte en complexiteit van de brongegevens, kunt u binnen enkele minuten een operationele index voor zoeken in volledige tekst hebben.

We raden u aan dezelfde regio of locatie te gebruiken voor zowel Azure Cognitive Search als Azure Cosmos DB voor een lagere latentie en om bandbreedtekosten te voorkomen.

Stap 1: brongegevens voorbereiden

U moet een Cosmos DB-account hebben, een Azure Cosmos DB-database die is SQL API of MongoDB-API (preview) en inhoud in de database.

Zorg ervoor dat Cosmos DB database gegevens bevat. De wizard Gegevens importeren leest metagegevens en voert gegevenssampling uit om een indexschema af te afleiden, maar laadt ook gegevens uit Cosmos DB. Als de gegevens ontbreken, stopt de wizard met de volgende fout: Fout bij het detecteren van het indexschema uit de gegevensbron: Kan geen prototype-index bouwen omdat de gegevensbron 'emptycollection' geen gegevens heeft geretourneerd.

Stap 2: wizard Gegevens importeren starten

U kunt de wizard starten via de opdrachtbalk op de pagina Azure Cognitive Search-service. Als u verbinding maakt met de Cosmos DB SQL-API, kunt u in de sectie Instellingen van het linkernavigatiedeelvenster van uw Cosmos DB-account op Azure Cognitive Search toevoegen klikken.

Stap 3: de gegevensbron instellen

Op de pagina gegevensbron moet de bron zijn Cosmos DB, met de volgende specificaties:

• Naam is de naam van het gegevensbronobject. Na het maken kunt u deze kiezen voor andere workloads.

• Cosmos DB account moet een van de volgende indelingen hebben:

  1. De primaire of secundaire connection string uit Cosmos DB met de volgende indeling: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>; .
     • Voor versie 3.2 en versie 3.6 gebruiken MongoDB-verzamelingen de volgende indeling voor het Cosmos DB-account in de Azure Portal: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;ApiKind=MongoDb
  2. Een beheerde identiteit connection string met de volgende indeling die geen accountsleutel bevat: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];) . Als u deze connection string wilt gebruiken, volgt u de instructies voor Het instellen van een indexeringsverbinding met een Cosmos DB-database met behulp van een beheerde identiteit.

• Database is een bestaande database van het account.

• Verzameling is een container met documenten. Documenten moeten bestaan om het importeren te laten slagen.

• De query kan leeg zijn als u alle documenten wilt, anders kunt u een query invoeren die een documentsubset selecteert. Query is alleen beschikbaar voor de SQL API.

  

Stap 4: de pagina Inhoud verrijken in de wizard overslaan

Het toevoegen van cognitieve vaardigheden (of verrijking) is geen importvereiste. Tenzij u een specifieke behoefte hebt om AI-verrijking toe te voegen aan uw indexeringspijplijn, kunt u deze stap overslaan.

Als u de stap wilt overslaan, klikt u op de blauwe knoppen onder aan de pagina voor 'Volgende' en 'Overslaan'.

Stap 5: indexkenmerken instellen

Op de pagina Index ziet u een lijst met velden met een gegevenstype en een reeks selectievakjes voor het instellen van indexkenmerken. De wizard kan een lijst met velden genereren op basis van metagegevens en door steekproeven te nemen van de brongegevens.

U kunt kenmerken bulksgewijs selecteren door op het selectievakje boven aan een kenmerkkolom te klikken. Kies Ophaalbaar en Doorzoekbaar voor elk veld dat moet worden geretourneerd naar een client-app en onderhevig is aan zoekopdrachten in volledige tekst. U ziet dat gehele getallen geen volledige tekst of fuzzy doorzoekbaar zijn (getallen worden verbatim geëvalueerd en zijn vaak nuttig in filters).

Bekijk de beschrijving van indexkenmerken en taalanalyses voor meer informatie.

Neem even de tijd om uw selecties te bekijken. Zodra u de wizard hebt uitgevoerd, worden fysieke gegevensstructuren gemaakt en kunt u deze velden niet bewerken zonder alle objecten te verwijderen en opnieuw te maken.

Stap 6: indexer maken

Volledig opgegeven maakt de wizard drie afzonderlijke objecten in uw zoekservice. Een gegevensbronobject en indexobject worden opgeslagen als benoemde resources in uw Azure Cognitive Search service. In de laatste stap wordt een indexeringsobject gemaakt. Door de indexer een naam te geven, kan deze bestaan als een zelfstandige resource, die u onafhankelijk van het index- en gegevensbronobject kunt plannen en beheren, dat in dezelfde wizardreeks is gemaakt.

Als u niet bekend bent met indexeringen, is een indexeringsfunctie een resource in Azure Cognitive Search die een externe gegevensbron verkent voor doorzoekbare inhoud. De uitvoer van de wizard Gegevens importeren is een indexeerfunctie die uw Cosmos DB-gegevensbron verkent, doorzoekbare inhoud extraheert en deze importeert in een index op Azure Cognitive Search.

In de volgende schermopname ziet u de standaardconfiguratie van de indexer. U kunt overschakelen naar Eenmaal als u de indexer één keer wilt uitvoeren. Klik op Verzenden om de wizard uit te voeren en alle objecten te maken. Het indexeren begint onmiddellijk.

U kunt het importeren van gegevens controleren op de portalpagina's. Voortgangsmeldingen geven de indexeringsstatus aan en het aantal documenten dat wordt geüpload.

Wanneer het indexeren is voltooid, kunt u Search Explorer gebruiken om een query uit te voeren op uw index.

REST-API's gebruiken

U kunt de REST API gebruiken om Azure Cosmos DB-gegevens te indexeren, volgens een driedelige werkstroom die voor alle indexeringen in Azure Cognitive Search wordt gebruikt: een gegevensbron maken, een index maken en een indexer maken. In het onderstaande proces wordt gegevensextractie Cosmos DB gestart wanneer u de aanvraag Indexer maken indient.

Eerder in dit artikel wordt vermeld dat Azure Cosmos DB indexeren en indexeren Azure Cognitive Search afzonderlijke bewerkingen zijn. Voor Cosmos DB indexering worden standaard alle documenten automatisch geïndexeerd. Als u automatisch indexeren uit schakelen, zijn documenten alleen toegankelijk via hun eigen koppelingen of door query's met behulp van de document-id. Azure Cognitive Search indexering moet Cosmos DB automatisch indexeren worden ingeschakeld in de verzameling die wordt geïndexeerd door Azure Cognitive Search.

Stap 1: invoer voor de aanvraag samenstellen

Voor elke aanvraag moet u de servicenaam en beheersleutel voor Azure Cognitive Search (in de POST-header) en de naam en sleutel van het opslagaccount voor blobopslag verstrekken. U kunt Postman of Visual Studio Code gebruiken om HTTP-aanvragen te verzenden naar Azure Cognitive Search.

Kopieer de volgende drie waarden voor gebruik met uw aanvraag:

• Azure Cognitive Search servicenaam
• Azure Cognitive Search-beheersleutel
• Cosmos DB connection string

U vindt deze waarden in de portal:

1. Kopieer op de portalpagina's Azure Cognitive Search zoekservice-URL van de pagina Overzicht.

2. Klik in het linkernavigatiedeelvenster op Sleutels en kopieer vervolgens de primaire of secundaire sleutel.

3. Schakel over naar de portalpagina's voor uw Cosmos-opslagaccount. Klik in het linkernavigatiedeelvenster Instellingen op Sleutels. Deze pagina bevat een URI, twee sets verbindingsreeksen en twee sets sleutels. Kopieer een van de verbindingsreeksen naar Kladblok.

Stap 2: een gegevensbron maken

Een gegevensbron geeft de gegevens op die moeten worden geïndexeerd, referenties en beleidsregels voor het identificeren van wijzigingen in de gegevens (zoals gewijzigde of verwijderde documenten in uw verzameling). De gegevensbron wordt gedefinieerd als een onafhankelijke resource, zodat deze kan worden gebruikt door meerdere indexeringen.

Formuleer een POST-aanvraag om een gegevensbron te maken:

    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"
        }
    }

De body van de aanvraag bevat de gegevensbrondefinitie, die de volgende velden moet bevatten:

Query's gebruiken om geïndexeerde gegevens vorm te geven

U kunt een query SQL geneste eigenschappen of matrices plat te maken, JSON-eigenschappen te projecteren en de gegevens te filteren die moeten worden geïndexeerd.

Voorbeelddocument:

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

Filterquery:

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

Query plat maken:

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

Projectiequery:

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 voor het plat maken van matrices:

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

DISTINCT en GROUP BY

Query's die gebruikmaken van het sleutelwoord DISTINCT of de GROUP BY-component worden niet ondersteund. Azure Cognitive Search is afhankelijk van SQL query paginering om de resultaten van de query volledig op te semuleren. Het sleutelwoord DISTINCT of de GROUP BY-component zijn niet compatibel met de vervolgtokens die worden gebruikt om resultaten te pagineren.

Voorbeelden van niet-ondersteunde query's:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Hoewel Cosmos DB een tijdelijke oplossing biedt ter ondersteuning van SQL query paginering met het sleutelwoord DISTINCT met behulp van de ORDER BY-component,is het niet compatibel met Azure Cognitive Search. De query retourneert één JSON-waarde, terwijl Azure Cognitive Search een JSON-object verwacht.

-- The following query returns a single JSON value and isn't supported by Azure Cognitive Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Stap 3: een doelzoekindex maken

Maak een doel Azure Cognitive Search index als u er nog geen hebt. In het volgende voorbeeld wordt een index gemaakt met een id- en beschrijvingsveld:

    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,
         "searchable": true,
         "sortable": false,
         "facetable": false,
         "suggestions": true
       }]
     }

Zorg ervoor dat het schema van uw doelindex compatibel is met het schema van de bron-JSON-documenten of de uitvoer van uw aangepaste queryprojectie.

Toewijzing tussen JSON-gegevenstypen en Azure Cognitive Search gegevenstypen

Stap 4: de indexer configureren en uitvoeren

Zodra de index en gegevensbron zijn gemaakt, kunt u de indexer maken:

    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" }
    }

Deze indexer wordt elke twee uur uitgevoerd (schema-interval is ingesteld op PT2H). Als u een indexer elke 30 minuten wilt uitvoeren, stelt u het interval in op PT30M. Het kortste ondersteunde interval is 5 minuten. De planning is optioneel. Als u dit weggelaten, wordt een indexer slechts één keer uitgevoerd wanneer deze wordt gemaakt. U kunt echter op elk moment een indexer op aanvraag uitvoeren.

Zie Indexer maken voor meer informatie over de Create Indexer-API.

Zie How to schedule indexers for Azure Cognitive Search voor meer informatie over het definiëren van indexeringsplanningen.

.NET gebruiken

De algemeen beschikbare .NET SDK heeft volledige pariteit met de algemeen beschikbare REST API. U wordt aangeraden de vorige sectie REST API voor meer informatie over concepten, werkstromen en vereisten. U kunt vervolgens verwijzen naar de volgende .NET API-referentiedocumentatie voor het implementeren van een JSON-indexer in beheerde code.

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

Gewijzigde documenten indexeren

Het doel van een beleid voor gegevenswijzigingsdetectie is het efficiënt identificeren van gewijzigde gegevensitems. Op dit moment is het enige ondersteunde beleid het gebruik van de HighWaterMarkChangeDetectionPolicy eigenschap (timestamp) van Azure Cosmos DB, die als _ts volgt wordt opgegeven:

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

Het gebruik van dit beleid wordt ten zeerste aanbevolen om goede prestaties van de indexer te garanderen.

Als u een aangepaste query gebruikt, moet u ervoor zorgen dat de _ts eigenschap wordt geprojecteerd door de query.

Incrementele voortgang en aangepaste query's

Incrementele voortgang tijdens het indexeren zorgt ervoor dat als de uitvoering van de indexer wordt onderbroken door tijdelijke fouten of de uitvoeringstijdlimiet, de indexer de volgende keer dat de indexer wordt uitgevoerd verder kan gaan waar deze is gebleven, in plaats van dat de hele verzameling helemaal opnieuw moet worden geïndexeerd. Dit is vooral belangrijk bij het indexeren van grote verzamelingen.

Als u incrementele voortgang wilt inschakelen bij het gebruik van een aangepaste query, zorgt u ervoor dat uw query de resultaten per kolom _ts bestelt. Hierdoor kunnen periodieke controles worden uitgevoerd die Azure Cognitive Search gebruikt om incrementele voortgang te bieden bij het optreden van storingen.

In sommige gevallen kan, zelfs als uw query een -component bevat, Azure Cognitive Search niet afleiden dat de ORDER BY [collection alias]._ts query is geordend door de _ts . U kunt aan Azure Cognitive Search zien dat de resultaten worden geordend met behulp van de assumeOrderByHighWaterMarkColumn configuratie-eigenschap . Als u deze hint wilt opgeven, maakt of werk u de indexeerer als volgt bij:

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

Verwijderde documenten indexeren

Wanneer rijen uit de verzameling worden verwijderd, wilt u deze rijen doorgaans ook uit de zoekindex verwijderen. Het doel van een beleid voor gegevensdetectie is het efficiënt identificeren van verwijderde gegevensitems. Op dit moment is het enige ondersteunde beleid het beleid (verwijderen is gemarkeerd met een vlag van een bepaalde vorm), die Soft Delete als volgt wordt opgegeven:

    {
        "@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"
    }

Als u een aangepaste query gebruikt, moet u ervoor zorgen dat de eigenschap waarnaar wordt softDeleteColumnName verwezen, wordt geprojecteerd door de query.

In het volgende voorbeeld wordt een gegevensbron gemaakt met een beleid voor zachte verwijdering:

    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"
        }
    }

Volgende stappen

Gefeliciteerd U hebt geleerd hoe u uw Azure Cosmos DB met Azure Cognitive Search met behulp van een indexer.

• Zie de pagina Azure Cosmos DB service voor Azure Cosmos DB meer informatie over uw service.
• Zie de pagina Azure Cognitive Search meer informatie over Search-service.