Indexera data från Azure Cosmos DB med SQL- eller MongoDB-API:er

Den här artikeln visar hur du konfigurerar en Azure Cosmos DB-indexerare för att extrahera innehåll och göra det sökbart i Azure Cognitive Search. Det här arbetsflödet skapar ett Azure Cognitive Search index och läser in det med befintlig text som extraherats från Azure Cosmos DB.

Eftersom terminologi kan vara förvirrande är det värt att notera att Azure Cosmos DB och Azure Cognitive Search är distinkta åtgärder som är unika för varje tjänst. Innan du börjar Azure Cognitive Search indexering måste Azure Cosmos DB redan finnas och innehålla data.

Den Cosmos DB indexeraren i Azure Cognitive Search crawla Azure Cosmos DB objekt som nås via följande protokoll.

• För SQL API,som är allmänt tillgängligt, kan du använda portalen , REST API, .NET SDKeller någon annan Azure SDK för att skapa datakällan och indexeraren.

• För MongoDB API (förhandsversion)kan du använda portalen eller REST API version 2020-06-30-Preview för att skapa datakällan och indexeraren.

Förutsättningar

Endast Cosmos DB samlingar med en indexeringsprincip inställd på Konsekvent stöds av Azure Cognitive Search. Indexering av samlingar med en Lazy-indexeringsprincip rekommenderas inte och kan resultera i data som saknas. Samlingar med indexering inaktiverat stöds inte.

Använda portalen

Den enklaste metoden för att Azure Cosmos DB objekt är att använda en guide i Azure Portal. Genom att samplingsdata och läsa metadata i containern kan guiden Importera data i Azure Cognitive Search skapa ett standardindex, mappa källfält till målindexfält och läsa in indexet i en enda åtgärd. Beroende på källdatas storlek och komplexitet kan du ha ett fungerande fulltextsökningsindex på några minuter.

Vi rekommenderar att du använder samma region eller plats för både Azure Cognitive Search och Azure Cosmos DB för kortare svarstider och för att undvika bandbreddskostnader.

Steg 1 – Förbereda källdata

Du bör ha ett Cosmos DB-konto, en Azure Cosmos DB-databas som är mappad till API:et för SQL eller MongoDB (förhandsversion) och innehållet i databasen.

Kontrollera att Cosmos DB innehåller data. Guiden Importera data läser metadata och utför datasampling för att ta fram ett indexschema, men den läser även in data från Cosmos DB. Om data saknas stoppas guiden med felet "Fel vid identifiering av indexschema från datakälla: Det gick inte att skapa ett prototypindex eftersom datakällan "emptycollection" inte returnerade några data".

Steg 2 – Starta guiden Importera data

Du kan starta guiden från kommandofältet på sidan för Azure Cognitive Search-tjänsten, eller om du ansluter till Cosmos DB SQL-API:et kan du klicka på Lägg till Azure Cognitive Search i avsnittet Inställningar i det vänstra navigeringsfönstret för Cosmos DB-kontot.

Steg 3 – Ange datakällan

På datakällsidan måste källan vara Cosmos DB, med följande specifikationer:

• Namn är namnet på datakällobjektet. När du har skapat den kan du välja den för andra arbetsbelastningar.

• Cosmos DB ska ha något av följande format:

  1. Den primära eller sekundära anslutningssträngen från Cosmos DB med följande format: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>; .
     • För MongoDB-samlingar av version 3.2 och version 3.6 använder du följande format för Cosmos DB-kontot i Azure Portal: AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;ApiKind=MongoDb
  2. En anslutningssträng för hanterad identitet med följande format som inte innehåller en kontonyckel: ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];) . Om du vill använda det här formatet för anslutningssträngen följer du anvisningarna för Att konfigurera en indexeraranslutning till en Cosmos DB-databas med en hanterad identitet.

• Databasen är en befintlig databas från kontot.

• Samling är en container med dokument. Dokument måste finnas för att importen ska lyckas.

• Frågan kan vara tom om du vill ha alla dokument, annars kan du ange en fråga som väljer en dokumentdelmängd. Frågan är bara tillgänglig för SQL API.

  

Steg 4 – Hoppa över sidan Berika innehåll i guiden

Att lägga till kognitiva kunskaper (eller berikning) är inte ett importkrav. Om du inte har ett specifikt behov av att lägga till AI-berikning i indexeringspipelinen kan du hoppa över det här steget.

Om du vill hoppa över steget klickar du på de blå knapparna längst ned på sidan för "Nästa" och "Hoppa över".

Steg 5 – Ange indexattribut

På sidan Index bör du se en lista över fält med en datatyp och en serie kryssrutor för att ange indexattribut. Guiden kan generera en fältlista baserat på metadata och genom att sampling av källdata.

Du kan massvälja attribut genom att klicka på kryssrutan överst i en attributkolumn. Välj Hämtningsbar och Sökbar för varje fält som ska returneras till en klientapp och omfattas av fulltextsökning. Du kommer att märka att heltal inte är fulltext eller fuzzy-sökbara (tal utvärderas ordagrann och är ofta användbara i filter).

Mer information finns i beskrivningen av indexattribut och språkanalysverktyg.

Granska dina val en stund. När du kör guiden skapas fysiska datastrukturer och du kan inte redigera dessa fält utan att släppa och återskapa alla objekt.

Steg 6 – Skapa indexerare

Guiden skapar tre distinkta objekt i söktjänsten. Ett datakällobjekt och indexobjekt sparas som namngivna resurser i din Azure Cognitive Search tjänst. Det sista steget skapar ett indexerarobjekt. Genom att namnge indexeraren kan den finnas som en fristående resurs som du kan schemalägga och hantera oberoende av indexet och datakällobjektet som skapats i samma guidesekvens.

Om du inte är bekant med indexerare är en indexerare en resurs i Azure Cognitive Search som crawlar en extern datakälla för sökbart innehåll. Utdata från guiden Importera data är en indexerare som söker igenom Cosmos DB datakälla, extraherar sökbart innehåll och importerar det till ett index på Azure Cognitive Search.

Följande skärmbild visar standardkonfigurationen för indexeraren. Du kan växla till En gång om du vill köra indexeraren en gång. Klicka på Skicka för att köra guiden och skapa alla objekt. Indexeringen börjar omedelbart.

Du kan övervaka dataimporten på portalsidorna. Förloppsmeddelanden anger indexeringsstatus och hur många dokument som laddas upp.

När indexeringen är klar kan du använda Sökutforskaren för att köra frågor mot ditt index.

Använda REST-API:er

Du kan använda REST API för att indexera Azure Cosmos DB-data genom att följa ett arbetsflöde i tre delar som är gemensamt för alla indexerare i Azure Cognitive Search: skapa en datakälla, skapa ett index och skapa en indexerare. I processen nedan startar extrahering av data Cosmos DB när du skickar begäran om att skapa indexeraren.

Tidigare i den här artikeln nämndes att Azure Cosmos DB och indexering Azure Cognitive Search indexering är distinkta åtgärder. För Cosmos DB indexering indexeras alla dokument automatiskt som standard. Om du inaktiverar automatisk indexering kan dokument endast nås via sina självlänkar eller via frågor med hjälp av dokument-ID:t. Azure Cognitive Search indexering kräver Cosmos DB att automatisk indexering aktiveras i samlingen som indexeras av Azure Cognitive Search.

Steg 1 – Sätt ihop indata för begäran

För varje begäran måste du ange tjänstnamnet och administratörsnyckeln för Azure Cognitive Search (i POST-huvudet) och lagringskontots namn och nyckel för bloblagring. Du kan använda Postman eller Visual Studio Code för att skicka HTTP-begäranden till Azure Cognitive Search.

Kopiera följande tre värden för användning med din begäran:

• Azure Cognitive Search tjänstnamn
• Azure Cognitive Search administratörsnyckel
• Cosmos DB anslutningssträng

Du hittar dessa värden i portalen:

1. På portalsidorna för Azure Cognitive Search kopierar du söktjänstens URL från sidan Översikt.

2. I det vänstra navigeringsfönstret klickar du på Nycklar och kopierar sedan antingen den primära eller sekundära nyckeln.

3. Växla till portalsidorna för ditt Cosmos-lagringskonto. I det vänstra navigeringsfönstret, under Inställningar, klickar du på Nycklar. Den här sidan innehåller en URI, två uppsättningar med anslutningssträngar och två uppsättningar nycklar. Kopiera en av anslutningssträngarna till Anteckningar.

Steg 2 – Skapa en datakälla

En datakälla anger data som ska indexeras, autentiseringsuppgifter och principer för att identifiera ändringar i data (till exempel ändrade eller borttagna dokument i din samling). Datakällan definieras som en oberoende resurs så att den kan användas av flera indexerare.

Formulera en POST-begäran för att skapa en datakälla:

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

Brödtexten i begäran innehåller datakällsdefinitionen, som bör innehålla följande fält:

Använda frågor för att forma indexerade data

Du kan ange en SQL fråga för att platta ut kapslade egenskaper eller matriser, projicera JSON-egenskaper och filtrera de data som ska indexeras.

Exempeldokument:

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

Filterfråga:

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

Utplattningsfråga:

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

Projektionsfråga:

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

Fråga om utplattning av matris:

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

DISTINCT och GROUP BY

Frågor som använder nyckelordet DISTINCT eller GROUP BY-satsen stöds inte. Azure Cognitive Search förlitar sig SQL på sidnumrering av frågor för att helt räkna upp resultatet av frågan. Varken nyckelordet DISTINCT eller GROUP BY-satsen är kompatibla med fortsättningstoken som används för att sidbryta resultat.

Exempel på frågor som inte stöds:

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

Även Cosmos DB har en lösning för att SQL sidnumrering med nyckelordet DISTINCTmed hjälp av ORDER BY-satsen är den inte kompatibel med Azure Cognitive Search. Frågan returnerar ett enda JSON-värde, medan Azure Cognitive Search förväntar sig ett JSON-objekt.

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

Steg 3 – Skapa ett målsökindex

Skapa ett Azure Cognitive Search index om du inte redan har ett. I följande exempel skapas ett index med ett ID- och beskrivningsfält:

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

Kontrollera att schemat för målindexet är kompatibelt med schemat för JSON-källdokumenten eller utdata från din anpassade frågeprojektion.

Mappning mellan JSON-datatyper Azure Cognitive Search datatyper

Steg 4 – Konfigurera och köra indexeraren

När indexet och datakällan har skapats är du redo att skapa indexeraren:

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

Den här indexeraren körs varannan timme (schemaintervallet är inställt på "PT2H"). Om du vill köra en indexerare var 30:e minut anger du intervallet till "PT30M". Det kortaste intervall som stöds är 5 minuter. Schemat är valfritt – om det utelämnas körs en indexerare bara en gång när den skapas. Du kan dock köra en indexerare på begäran när som helst.

Mer information om API:et för att skapa indexerare finns i Skapa indexerare.

Mer information om hur du definierar indexerarscheman finns i Schemalägga indexerare för Azure Cognitive Search.

Använda .NET

Den allmänt tillgängliga .NET SDK:n har fullständig paritet med den allmänt tillgängliga REST API. Vi rekommenderar att du går igenom föregående REST API för att lära dig begrepp, arbetsflöde och krav. Du kan sedan läsa följande .NET API-referensdokumentation för att implementera en JSON-indexerare i hanterad kod.

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

Indexera ändrade dokument

Syftet med en princip för dataändringsidentifiering är att effektivt identifiera ändrade dataobjekt. För närvarande är den enda princip som stöds egenskapen HighWaterMarkChangeDetectionPolicy using _ts the (timestamp) som tillhandahålls av Azure Cosmos DB, som anges på följande sätt:

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

Vi rekommenderar starkt att du använder den här principen för att säkerställa bra indexerarprestanda.

Om du använder en anpassad fråga kontrollerar du att _ts egenskapen projiceras av frågan.

Inkrementell förlopp och anpassade frågor

Inkrementell förlopp under indexering säkerställer att om indexerarkörningen avbryts av tillfälliga fel eller en tidsgräns för körning kan indexeraren fortsätta där den slutade nästa gång den körs, i stället för att behöva indexera om hela samlingen från grunden. Detta är särskilt viktigt när du indexerar stora samlingar.

Om du vill aktivera stegvisa förlopp när du använder en anpassad fråga, se till att frågan beställer resultatet av _ts kolumnen. Detta möjliggör periodisk kontroll som används Azure Cognitive Search för att tillhandahålla stegvisa förlopp i närvaro av fel.

I vissa fall, även om din fråga innehåller en -Azure Cognitive Search kan det hända att frågan ORDER BY [collection alias]._ts inte är sorterad efter _ts . Du kan se Azure Cognitive Search resultaten sorteras med hjälp av assumeOrderByHighWaterMarkColumn konfigurationsegenskapen. Om du vill ange det här tipset skapar eller uppdaterar du indexeraren på följande sätt:

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

Indexera borttagna dokument

När rader tas bort från samlingen vill du normalt även ta bort dessa rader från sökindexet. Syftet med en princip för identifiering av databorttagning är att effektivt identifiera borttagna dataobjekt. Den enda princip som stöds är för närvarande principen (borttagningen markeras med en flagga Soft Delete av någon typ), som anges på följande sätt:

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

Om du använder en anpassad fråga kontrollerar du att den egenskap som refereras softDeleteColumnName till av projiceras av frågan.

I följande exempel skapas en datakälla med en princip för mjuk borttagning:

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

Nästa steg

Grattis! Du har lärt dig hur du integrerar Azure Cosmos DB med Azure Cognitive Search med hjälp av en indexerare.

• Mer information om Azure Cosmos DB finns på Azure Cosmos DB tjänstsidan.
• Mer information om Azure Cognitive Search finns på tjänsten Search sidan.