Gegevens indexeren uit Azure Cosmos DB voor MongoDB voor query's in Azure AI Search

  • Artikel

Belangrijk

MongoDB API-ondersteuning is momenteel beschikbaar als openbare preview onder aanvullende gebruiksvoorwaarden. Momenteel is er geen SDK-ondersteuning.

In dit artikel leert u hoe u een indexeerfunctie configureert waarmee inhoud uit Azure Cosmos DB voor MongoDB wordt geïmporteerd en hoe u deze doorzoekbaar maakt in Azure AI Search.

Dit artikel is een aanvulling op Het maken van een indexeerfunctie met informatie die specifiek is voor Cosmos DB. Hierbij worden de REST API's gebruikt om een driedelige werkstroom te demonstreren die gebruikelijk is voor alle indexeerfuncties: een gegevensbron maken, een index maken, een indexeerfunctie maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken verzendt.

Omdat terminologie verwarrend kan zijn, is het de moeite waard om te vermelden dat azure Cosmos DB-indexering en Azure AI Search-indexering verschillende bewerkingen zijn. Indexering in Azure AI Search maakt en laadt een zoekindex in uw zoekservice.

Vereisten

  • Registreer u voor de preview om feedback over scenario's te geven. U hebt automatisch toegang tot de functie na het verzenden van formulieren.

  • Een Azure Cosmos DB-account, -database, -verzameling en -documenten. Gebruik dezelfde regio voor zowel Azure AI Search als Azure Cosmos DB voor lagere latentie en om bandbreedtekosten te voorkomen.

  • Een automatisch indexeringsbeleid voor de Azure Cosmos DB-verzameling, ingesteld op Consistent. Dit is de standaard configuratie. Luie indexering wordt niet aanbevolen en kan leiden tot ontbrekende gegevens.

  • Leesmachtigingen. Een 'volledige toegang' verbindingsreeks bevat een sleutel die toegang verleent tot de inhoud, maar als u Azure-rollen gebruikt, moet u ervoor zorgen dat de door de zoekservice beheerde identiteit machtigingen heeft voor de rol lezer van het Cosmos DB-account.

  • Een REST-client voor het maken van de gegevensbron, index en indexeerfunctie.

Beperkingen

Dit zijn de beperkingen van deze functie:

  • Aangepaste query's worden niet ondersteund voor het opgeven van de gegevensset.

  • De kolomnaam _ts is een gereserveerd woord. Als u dit veld nodig hebt, kunt u alternatieve oplossingen overwegen voor het vullen van een index.

  • Het MongoDB-kenmerk $ref is een gereserveerd woord. Als u dit nodig hebt in uw MongoDB-verzameling, kunt u alternatieve oplossingen overwegen voor het invullen van een index.

Als alternatief voor deze connector, als uw scenario een van deze vereisten heeft, kunt u de Push-API/SDK gebruiken of Azure Data Factory overwegen met een Azure AI Search-index als sink.

De gegevensbron definiëren

De definitie van de gegevensbron geeft de gegevens op die moeten worden geïndexeerde, referenties en beleidsregels voor het identificeren van wijzigingen in de gegevens. Een gegevensbron wordt gedefinieerd als een onafhankelijke resource, zodat deze kan worden gebruikt door meerdere indexeerfuncties.

Geef voor deze aanroep een preview-REST API-versie op (2020-06-30-Preview of 2021-04-30-Preview) om een gegevensbron te maken die verbinding maakt via de MongoDB-API.

  1. Een gegevensbron maken of bijwerken om de definitie ervan in te stellen:

    POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-Preview
Content-Type: application/json
api-key: [Search service admin key]
{
  "name": "[my-cosmosdb-mongodb-ds]",
  "type": "cosmosdb",
  "credentials": {
    "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDb;"
  },
  "container": {
    "name": "[cosmos-db-collection]",
    "query": null
  },
  "dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "highWaterMarkColumnName": "_ts"
  },
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null,
  "identity": null
}

  2. Stel 'type' in op "cosmosdb" (vereist).

  3. Stel referenties in op een verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.

  4. Stel 'container' in op de verzameling. De eigenschap 'name' is vereist en geeft de id van de databaseverzameling op die moet worden geïndexeerd. Voor Azure Cosmos DB voor MongoDB wordt 'query' niet ondersteund.

  5. Stel dataChangeDetectionPolicy in als de gegevens vluchtig zijn en u wilt dat de indexeerfunctie alleen de nieuwe en bijgewerkte items ophaalt bij volgende uitvoeringen.

  6. Stel 'dataDeletionDetectionPolicy' in als u zoekdocumenten uit een zoekindex wilt verwijderen wanneer het bronitem wordt verwijderd.

Ondersteunde referenties en verbindingsreeks s

Indexeerfuncties kunnen verbinding maken met een verzameling met behulp van de volgende verbindingen. Voor verbindingen die zijn gericht op de MongoDB-API, moet u 'ApiKind' opnemen in de verbindingsreeks.

Vermijd poortnummers in de eindpunt-URL. Als u het poortnummer opneemt, mislukt de verbinding.

Volledige toegang verbindingsreeks
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
U kunt de Cosmos DB-verificatiesleutel ophalen op de pagina van het Azure Cosmos DB-account in Azure Portal door Verbinding maken ion-tekenreeks in het linkernavigatiedeelvenster te selecteren. Zorg ervoor dat u het primaire wachtwoord kopieert en de waarde van de Cosmos DB-verificatiesleutel vervangt.
Beheerde identiteit verbindingsreeks
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }
Voor deze verbindingsreeks is geen accountsleutel vereist, maar u moet eerder een zoekservice hebben geconfigureerd om verbinding te maken met behulp van een beheerde identiteit en een roltoewijzing hebt gemaakt waarmee cosmos DB-accountlezer rolmachtigingen worden verleend. Zie Een indexeerfunctieverbinding met een Azure Cosmos DB-database instellen met behulp van een beheerde identiteit voor meer informatie.

Zoekvelden toevoegen aan een index

Voeg in een zoekindex velden toe om de bron-JSON-documenten of de uitvoer van uw aangepaste queryprojectie te accepteren. Zorg ervoor dat het zoekindexschema compatibel is met brongegevens. Voor inhoud in Azure Cosmos DB moet uw zoekindexschema overeenkomen met de Azure Cosmos DB-items in uw gegevensbron.

  1. Maak of werk een index bij om zoekvelden te definiëren waarmee gegevens worden opgeslagen:

    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": "doc_id",
        "type": "Edm.String",
        "key": true,
        "retrievable": true,
        "searchable": false
    }, {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }]
}

  2. Maak een documentsleutelveld ('sleutel': true'). Voor een zoekindex op basis van een MongoDB-verzameling kan de documentsleutel 'doc_id', 'rid' of een ander tekenreeksveld met unieke waarden zijn. Zolang veldnamen en gegevenstypen aan beide zijden hetzelfde zijn, zijn er geen veldtoewijzingen vereist.

    • 'doc_id' vertegenwoordigt '_id' voor de object-id. Als u een veld van 'doc_id' in de index opgeeft, wordt dit door de indexeerfunctie gevuld met de waarden van de object-id.

    • Rid is een systeemeigenschap in Azure Cosmos DB. Als u een veld van 'rid' opgeeft in de index, wordt dit door de indexeerfunctie gevuld met de base64-gecodeerde waarde van de eigenschap Rid.

    • Voor elk ander veld moet uw zoekveld dezelfde naam hebben als gedefinieerd in de verzameling.

  3. Maak extra velden voor meer doorzoekbare inhoud. Zie Een index maken voor meer informatie.

Toewijzingsgegevenstypen

JSON-gegevenstype Azure AI Search-veldtypen
Bool Edm.Boolean, Edm.String
Getallen die eruitzien als gehele getallen Edm.Int32, Edm.Int64, Edm.String
Getallen die eruitzien als drijvende punten Edm.Double, Edm.String
String Edm.String
Matrices van primitieve typen, zoals ["a", "b", "c"] Collection(Edm.String)
Tekenreeksen die eruitzien als datums Edm.DateTimeOffset, Edm.String
GeoJSON-objecten zoals { "type": "Point", "coördinaten": [long, lat] } Edm.GeographyPoint
Andere JSON-objecten N.v.t.

De Indexeerfunctie van Azure Cosmos DB voor MongoDB configureren en uitvoeren

Zodra de index en de gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen aan die het gedrag van de uitvoeringstijd regelen.

  1. Maak of werk een indexeerfunctie bij door deze een naam te geven en te verwijzen naar de gegevensbron en doelindex:

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-mongodb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt.

  3. Zie Een indexeerfunctie maken voor meer informatie over andere eigenschappen.

Een indexeerfunctie wordt automatisch uitgevoerd wanneer deze wordt gemaakt. U kunt dit voorkomen door 'uitgeschakeld' in te stellen op waar. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt controleren, verzendt u een get-indexeerstatusaanvraag :

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

Het antwoord bevat de status en het aantal verwerkte items. Het moet er ongeveer uitzien als in het volgende voorbeeld:

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

De uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in de omgekeerde chronologische volgorde worden gesorteerd, zodat de laatste uitvoering als eerste wordt uitgevoerd.

Nieuwe en gewijzigde documenten indexeren

Zodra een indexeerfunctie een zoekindex volledig heeft ingevuld, wilt u mogelijk dat de volgende indexeerfunctie alleen de nieuwe en gewijzigde documenten in uw database incrementeel indexeren.

Als u incrementele indexering wilt inschakelen, stelt u de eigenschap dataChangeDetectionPolicy in uw gegevensbrondefinitie in. Deze eigenschap vertelt de indexeerfunctie welk mechanisme voor het bijhouden van wijzigingen wordt gebruikt voor uw gegevens.

Voor Indexeerfuncties van Azure Cosmos DB is het enige ondersteunde beleid het HighWaterMarkChangeDetectionPolicy gebruik van de _ts eigenschap (timestamp) van Azure Cosmos DB.

In het volgende voorbeeld ziet u een definitie van een gegevensbron met een wijzigingsdetectiebeleid:

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

Verwijderde documenten indexeren

Wanneer rijen uit de verzameling worden verwijderd, wilt u deze rijen normaal gesproken ook uit de zoekindex verwijderen. Het doel van een beleid voor het detecteren van gegevensverwijdering is om verwijderde gegevensitems efficiënt te identificeren. Op dit moment is het enige ondersteunde beleid het Soft Delete beleid (verwijderen is gemarkeerd met een vlag van een bepaalde soort), die als volgt is opgegeven in de definitie van de gegevensbron:

"dataDeletionDetectionPolicy"": {
    "@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 verwezen softDeleteColumnName door de query wordt geprojecteerd.

In het volgende voorbeeld wordt een gegevensbron gemaakt met een beleid voor voorlopig verwijderen:

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

{
    "name": ["my-cosmosdb-mongodb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=MongoDB"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Volgende stappen

U kunt nu bepalen hoe u de indexeerfunctie uitvoert, de status bewaakt of de uitvoering van de indexeerfunctie plant. De volgende artikelen zijn van toepassing op indexeerfuncties die inhoud ophalen uit Azure Cosmos DB: