Kurz: Indexování vnořených objektů blob JSON ze služby Azure Storage pomocí REST

Článek
03/15/2024

Azure AI Search může indexovat dokumenty a pole JSON ve službě Azure Blob Storage pomocí indexeru, který ví, jak číst částečně strukturovaná data. Částečně strukturovaná data obsahují značky nebo označení oddělující obsah v rámci dat. Rozdělí rozdíl mezi nestrukturovanými daty, která musí být plně indexována, a formálně strukturovanými daty, která dodržují datový model, jako je schéma relační databáze, které je možné indexovat pro jednotlivá pole.

V tomto kurzu se dozvíte, jak indexovat vnořené pole JSON. K provádění následujících úloh používá klienta REST a rozhraní REST API služby Search:

Nastavení ukázkových dat a konfigurace azureblob zdroje dat
Vytvoření indexu Azure AI Search, který bude obsahovat prohledávatelný obsah
Vytvoření a spuštění indexeru pro čtení kontejneru a extrakci prohledávatelného obsahu
Prohledávání právě vytvořeného indexu

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Požadavky

Visual Studio Code s klientem REST
Azure Storage
Azure AI Search. Vytvořte nebo najděte existující prostředek služby Azure AI Search v rámci vašeho aktuálního předplatného.

Poznámka:

Pro účely tohoto kurzu můžete použít bezplatnou službu. Bezplatná vyhledávací služba vás omezuje na tři indexy, tři indexery a tři zdroje dat. V tomto kurzu se vytváří od každého jeden. Než začnete, ujistěte se, že máte ve službě místo pro přijetí nových prostředků.

Stažení souborů

Stáhněte si soubor ZIP ukázkového úložiště dat a extrahujte obsah. Zjistěte jak.

ny-free

Ukázková data jsou jeden soubor JSON obsahující pole JSON a 1 521 vnořených elementů JSON. Ukázková data pocházejí z historie výkonu NY na Kaggle. Zvolili jsme jeden soubor JSON, abychom zůstali pod limity úložiště úrovně Free.

Tady je první vnořený json v souboru. Zbývající část souboru obsahuje 1 520 dalších instancí koncertů.

    {
      "id": "7358870b-65c8-43d5-ab56-514bde52db88-0.1",
      "programID": "11640",
      "orchestra": "New York Philharmonic",
      "season": "2011-12",
      "concerts": [
        {
          "eventType": "Non-Subscription",
          "Location": "Manhattan, NY",
          "Venue": "Avery Fisher Hall",
          "Date": "2011-09-07T04:00:00Z",
          "Time": "7:30PM"
        },
        {
          "eventType": "Non-Subscription",
          "Location": "Manhattan, NY",
          "Venue": "Avery Fisher Hall",
          "Date": "2011-09-08T04:00:00Z",
          "Time": "7:30PM"
        }
      ],
      "works": [
        {
          "ID": "5733*",
          "composerName": "Bernstein,  Leonard",
          "workTitle": "WEST SIDE STORY (WITH FILM)",
          "conductorName": "Newman, David",
          "soloists": []
        },
        {
          "ID": "0*",
          "interval": "Intermission",
          "soloists": []
        }
      ]
    }

Nahrání ukázkových dat do Azure Storage

Ve službě Azure Storage vytvořte nový kontejner a pojmenujte ho bez přípony.
Nahrajte ukázkové datové soubory.
Získejte připojovací řetězec úložiště, abyste mohli formulovat připojení ve službě Azure AI Search.
1. Na levé straně vyberte Přístupové klávesy.
2. Zkopírujte připojovací řetězec pro klíč jeden nebo dva. Připojovací řetězec se podobá následujícímu příkladu:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Zkopírování adresy URL vyhledávací služby a klíče rozhraní API

Pro účely tohoto kurzu vyžadují připojení ke službě Azure AI Search koncový bod a klíč rozhraní API. Tyto hodnoty můžete získat z webu Azure Portal.

Přihlaste se k webu Azure Portal, přejděte na stránku Přehled vyhledávací služby a zkopírujte adresu URL. Příkladem koncového bodu může být https://mydemo.search.windows.net.
V části Nastavení> Klíče zkopírujte klíč správce. Správa klíče slouží k přidávání, úpravám a odstraňování objektů. Existují dva zaměnitelné klíče správce. Zkopírujte jeden z nich.

Nastavení souboru REST

Spusťte Visual Studio Code a vytvořte nový soubor.

Zadejte hodnoty proměnných použitých v požadavku:

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE

Uložte soubor pomocí přípony .rest nebo .http souboru.

Viz Rychlý start: Vyhledávání textu pomocí REST , pokud potřebujete pomoc s klientem REST.

Vytvoření zdroje dat

Vytvoření zdroje dat (REST) vytvoří připojení ke zdroji dat, které určuje, jaká data se mají indexovat.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name" : "ny-philharmonic-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Odešlete požadavek. Odpověď by měla vypadat nějak takto:

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
ETag: "0x8DC43A5FDB8448F"
Location: https://free-demo-search-svc.search.windows.net:443/datasources('ny-philharmonic-ds')?api-version=2023-11-01
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: 7ca53f73-1054-4959-bc1f-616148a9c74a
elapsed-time: 111
Date: Wed, 13 Mar 2024 21:38:58 GMT
Connection: close

{
  "@odata.context": "https://free-demo-search-svc.search.windows.net/$metadata#datasources/$entity",
  "@odata.etag": "\"0x8DC43A5FDB8448F\"",
  "name": "ny-philharmonic-ds",
  "description": null,
  "type": "azureblob",
  "subtype": null,
  "credentials": {
    "connectionString": null
  },
  "container": {
    "name": "ny-philharmonic-free",
    "query": null
  },
  "dataChangeDetectionPolicy": null,
  "dataDeletionDetectionPolicy": null,
  "encryptionKey": null
}

Vytvoření indexu

Vytvoření indexu (REST) vytvoří vyhledávací index ve vyhledávací službě. Index určuje všechny parametry a jejich atributy.

Vnořená pole JSON musí být stejná jako zdrojová pole. Azure AI Search v současné době nepodporuje mapování polí na vnořené JSON. Z tohoto důvodu se názvy polí a datové typy musí shodovat úplně. Následující index odpovídá elementům JSON v nezpracovaného obsahu.

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
      "name": "ny-philharmonic-index",  
      "fields": [
        {"name": "programID", "type": "Edm.String", "key": true, "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "orchestra", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        {"name": "season", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "facetable": true, "sortable": true},
        { "name": "concerts", "type": "Collection(Edm.ComplexType)", 
          "fields": [
            { "name": "eventType", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false},
            { "name": "Location", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Venue", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Date", "type": "Edm.String", "searchable": false, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "Time", "type": "Edm.String", "searchable": false, "retrievable": true, "filterable": true, "sortable": false, "facetable": true }
          ]
        },
        { "name": "works", "type": "Collection(Edm.ComplexType)", 
          "fields": [
            { "name": "ID", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false},
            { "name": "composerName", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "workTitle", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "conductorName", "type": "Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true },
            { "name": "soloists", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true, "filterable": true, "sortable": false, "facetable": true }
          ]
        }
      ]
    }

Klíčové body:

Mapování polí nemůžete použít k odsouhlasení rozdílů v názvech polí nebo datových typech. Toto schéma indexu je navržené tak, aby zrcadlily nezpracovaný obsah.
Vnořený JSON je modelován jako Collection(Edm.ComplextType). V nezpracovaném obsahu je pro každou sezónu více koncertů a více děl pro každý koncert. Pro přizpůsobení této struktury použijte kolekce pro komplexní typy.
V nezpracovaném obsahu Date a Time jsou to řetězce, takže odpovídající datové typy v indexu jsou také řetězce.

Vytvoření a spuštění indexeru

Vytvoření indexeru vytvoří indexer ve vyhledávací službě. Indexer se připojí ke zdroji dat, načte a indexuje data a volitelně poskytuje plán pro automatizaci aktualizace dat.

Konfigurace indexeru jsonArray zahrnuje režim analýzy a .documentRoot

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
      "name" : "ny-philharmonic-indexer",
      "dataSourceName" : "ny-philharmonic-ds",
      "targetIndexName" : "ny-philharmonic-index",
      "parameters" : { 
        "configuration" : { 
          "parsingMode" : "jsonArray", "documentRoot": "/programs"}
        },
      "fieldMappings" : [ 
      ]
    }

Klíčové body:

Nezpracovaný soubor obsahu obsahuje pole JSON ("programs") s 1 526 vnořenými strukturami JSON. Nastaví parsingMode se tak, aby jsonArray indexeru řekl, že každý objekt blob obsahuje pole JSON. Vzhledem k tomu, že vnořený JSON začíná o jednu úroveň dolů, nastaví documentRoot se na /programshodnotu .
Indexer běží několik minut. Před spuštěním jakýchkoli dotazů počkejte na dokončení provádění indexeru.

Spouštění dotazů

Hledání můžete začít hned, jak se načte první dokument.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "count": true
  }

Odešlete požadavek. Jedná se o nezadáný fulltextový vyhledávací dotaz, který vrátí všechna pole označená jako zobrazitelná v indexu spolu s počtem dokumentů. Odpověď by měla vypadat nějak takto:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/10.0
Strict-Transport-Security: max-age=2592000, max-age=15724800; includeSubDomains
Preference-Applied: odata.include-annotations="*"
OData-Version: 4.0
request-id: a95c4021-f7b4-450b-ba55-596e59ecb6ec
elapsed-time: 106
Date: Wed, 13 Mar 2024 22:09:59 GMT
Connection: close

{
  "@odata.context": "https://free-demo-search-svc.search.windows.net/indexes('ny-philharmonic-index')/$metadata#docs(*)",
  "@odata.count": 1521,
  "@search.nextPageParameters": {
    "search": "*",
    "count": true,
    "skip": 50
  },
  "value": [
  ],
  "@odata.nextLink": "https://free-demo-search-svc.search.windows.net/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01"
}

search Přidejte parametr pro hledání řetězce. select Přidejte parametr, který omezí výsledky na méně polí. filter Přidejte k dalšímu zúžení hledání.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "puccini",
    "count": true,
    "select": "season, concerts/Date, works/composerName, works/workTitle",
    "filter": "season gt '2015-16'"
  }

V odpovědi se vrátí dva dokumenty.

U filtrů můžete také použít logické operátory (a nebo ne) a relační operátory (eq, ne, gt, lt, ge, le). Při porovnávání řetězců se rozlišují malá a velká písmena. Další informace a příklady najdete v tématu Vytvoření dotazu.

Poznámka:

Parametr $filter funguje jenom u polí, která byla označena jako filtrovatelná při vytváření indexu.

Resetování a opětovné spuštění

Indexery je možné resetovat, vymazat historii provádění, což umožňuje úplné opětovné spuštění. Následující požadavky GET jsou určené k resetování a následné opětovné spuštění.

### Reset the indexer
POST {{baseUrl}}/indexers/ny-philharmonic-indexer/reset?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

### Run the indexer
POST {{baseUrl}}/indexers/ny-philharmonic-indexer/run?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

### Check indexer status 
GET {{baseUrl}}/indexers/ny-philharmonic-indexer/status?api-version=2023-11-01  HTTP/1.1
  api-key: {{apiKey}}

Vyčištění prostředků

Když pracujete ve vlastním předplatném, je na konci projektu vhodné odebrat prostředky, které už nepotřebujete. Prostředky, které necháte spuštěné, vás stojí peníze. Prostředky můžete odstraňovat jednotlivě nebo můžete odstranit skupinu prostředků, a odstranit tak celou sadu prostředků najednou.

Pomocí portálu můžete odstranit indexy, indexery a zdroje dat.

Další kroky

Teď, když znáte základy indexování objektů blob v Azure, se podrobněji podíváme na konfiguraci indexeru pro objekty blob JSON ve službě Azure Storage.

Konfigurace indexování objektů blob JSON

Sdílet prostřednictvím