Indexeer gegevens uit Azure Cosmos DB voor MongoDB voor query's in Azure AI Zoeken (preview)

De Azure Cosmos DB voor MongoDB-indexeerfunctie (preview) importeert inhoud uit Azure Cosmos DB voor MongoDB en maakt het doorzoekbaar in Azure AI Zoeken.

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 Zoeken indexering verschillende bewerkingen zijn. Indexeren in Azure AI Zoeken maakt en laadt een zoekindex in uw zoekservice.

Voorwaarden

• Vul het registratieformulier voor de indexeerfunctie in. Registratie wordt automatisch goedgekeurd.

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

• Een automatische indexeringsbeleid in de verzameling Azure Cosmos DB ingesteld op Consistent. Deze instelling is de standaardconfiguratie. 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 beheerde identiteit van de searchservice de rechten voor de rol Cosmos DB-accountlezer heeft.

• 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 kunt u, als uw scenario een van deze vereisten heeft, de Push-API/SDK of overwegen Azure Data Factory te gebruiken met een Azure AI Zoeken 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 om een gegevensbron te maken die verbinding maakt via de MongoDB-API. U kunt 2020-06-30-preview of hoger gebruiken. We raden de nieuwste preview-REST API aan.

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

   POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-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]"
     },
     "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 collectie. 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 verbindingsreeksen

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.

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. Een index maken of bijwerken om zoekvelden te definiëren waarmee gegevens worden opgeslagen:

   POST https://[service name].search.windows.net/indexes?api-version=2026-08-01-preview
   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.

Toewijzen van gegevenstypen

De Azure Cosmos DB voor mongoDB-indexeerfunctie 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=2026-08-01-preview
   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 true. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

Status van 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=2026-08-01-preview
  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 Azure Cosmos DB indexeerfuncties is het enige ondersteunde beleid de HighWaterMarkChangeDetectionPolicy met behulp van de eigenschap _ts (timestamp) die wordt geleverd door 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=2026-08-01-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": "[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:

• Een indexeerfunctieverbinding met een Azure Cosmos DB-database instellen met behulp van een beheerde identiteit
• Grote gegevenssets indexeren
• Indexer-toegang tot inhoud die wordt beveiligd door Azure netwerkbeveiligingsfuncties