Oktatóanyag: Beágyazott JSON-blobok indexelése az Azure Storage-ból REST használatával

Cikk
03/19/2024

Az Azure AI Search képes JSON-dokumentumokat és tömböket indexelni az Azure Blob Storage-ban egy olyan indexelő használatával, amely képes félig strukturált adatok olvasására. A részben strukturált adatok címkéket és jelölőket tartalmaznak, amelyek a tartalmakat választják el az adatokon belül. Felosztja a különbséget a strukturálatlan adatok között, amelyeket teljes mértékben indexelni kell, és formálisan strukturált adatok, amelyek megfelelnek egy adatmodellnek, például egy mezőnként indexelhető relációs adatbázisséma között.

Ez az oktatóanyag bemutatja a beágyazott JSON-tömbök indexeléséhez. REST-ügyfelet és a Search REST API-kat használ a következő feladatok végrehajtásához:

Mintaadatok beállítása és adatforrás konfigurálása azureblob
Kereshető tartalmakat tartalmazó Azure AI Search-index létrehozása
Indexelő létrehozása és futtatása a tároló olvasásához és kereshető tartalom kinyeréséhez
Keresés az újonnan létrehozott indexben

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Előfeltételek

Visual Studio Code REST-ügyféllel.
Azure Storage
Azure AI Search. Hozzon létre vagy keressen egy meglévő Azure AI Search-erőforrást az aktuális előfizetése alatt.

Feljegyzés

Ehhez az oktatóanyaghoz használhatja az ingyenes szolgáltatást. Az ingyenes keresési szolgáltatás három indexre, három indexelőre és három adatforrásra korlátozza. Az oktatóanyagban mindegyikből egyet hozhat majd létre. Mielőtt hozzákezdene, győződjön meg arról, hogy van helye a szolgáltatásban az új erőforrások elfogadásához.

Fájlok letöltése

Töltse le a mintaadattár zip-fájlját, és bontsa ki a tartalmat. További tudnivalókat itt talál.

ny-filharmónia-mentes

A mintaadatok egyetlen JSON-fájl, amely egy JSON-tömböt és 1521 beágyazott JSON-elemet tartalmaz. A mintaadatok a Kaggle ny filharmonikus teljesítményelőzményeiből származnak. Egy JSON-fájlt választottunk, amely az ingyenes szint tárolási korlátai alatt marad.

Itt található az első beágyazott JSON a fájlban. A fájl fennmaradó része 1520 további koncertelőadási példányt tartalmaz.

    {
      "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": []
        }
      ]
    }

Mintaadatok feltöltése az Azure Storage-ba

Az Azure Storage-ban hozzon létre egy új tárolót, és nevezze el ny-filharmóniamentesnek.
Töltse fel a mintaadatfájlokat.
Szerezze be a tárolási kapcsolati sztring, hogy kapcsolatot alakíthass ki az Azure AI Searchben.
1. A bal oldalon válassza az Access-kulcsokat.
2. Másolja a kapcsolati sztring az első vagy a második kulcshoz. A kapcsolati sztring a következő példához hasonló:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Keresési szolgáltatás URL-címének és API-kulcsának másolása

Ebben az oktatóanyagban az Azure AI Searchhez való csatlakozáshoz végpontra és API-kulcsra van szükség. Ezeket az értékeket az Azure Portalon szerezheti be.

Jelentkezzen be az Azure Portalra, lépjen a keresési szolgáltatás áttekintési oldalára, és másolja az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.
A Gépház> Keys területen másolja a rendszergazdai kulcsot. Rendszergazda kulcsok objektumok hozzáadására, módosítására és törlésére szolgálnak. Két felcserélhető rendszergazdai kulcs van. Másolja valamelyiket.

A REST-fájl beállítása

Indítsa el a Visual Studio Code-ot, és hozzon létre egy új fájlt

Adja meg a kérelemben használt változók értékeit:

@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

Mentse a fájlt egy vagy .http egy .rest fájlkiterjesztés használatával.

Lásd : Rövid útmutató: Szövegkeresés REST használatával, ha segítségre van szüksége a REST-ügyféllel kapcsolatban.

Adatforrás létrehozása

Az Adatforrás létrehozása (REST) létrehoz egy adatforrás-kapcsolatot, amely meghatározza az indexelendő adatokat.

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

Küldje el a kérést. A válasznak így kell kinéznie:

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
}

Index létrehozása

Az Index létrehozása (REST) létrehoz egy keresési indexet a keresési szolgáltatásban. Az index határozza meg az összes paramétert és ezek attribútumait.

Beágyazott JSON esetén az indexmezőknek meg kell egyezniük a forrásmezőkével. Az Azure AI Search jelenleg nem támogatja a beágyazott JSON-ra való mezőleképezést. Ezért a mezőneveknek és adattípusoknak teljesen egyeznie kell. Az alábbi index a nyers tartalom JSON-elemeihez igazodik.

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

Főbb pontok:

A mezőleképezések nem használhatók a mezőnevek és adattípusok közötti különbségek egyeztetésére. Ez az indexséma a nyers tartalom tükrözésére lett kialakítva.
A beágyazott JSON modellje a Collection(Edm.ComplextType). A nyers tartalomban minden szezonban több koncert, és minden koncerthez több mű is tartozik. A struktúra elhelyezéséhez használjon gyűjteményeket összetett típusokhoz.
A nyers tartalomban sztringek DateTime , így az index megfelelő adattípusai is sztringek.

Indexelő létrehozása és futtatása

Az Indexelő létrehozása létrehoz egy indexelőt a keresési szolgáltatásban. Az indexelő csatlakozik az adatforráshoz, betölti és indexeli az adatokat, és opcionálisan ütemezést biztosít az adatfrissítés automatizálásához.

Az indexelő konfigurációja magában foglalja az jsonArray elemzési módot és 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" : [ 
      ]
    }

Főbb pontok:

A nyers tartalomfájl egy JSON-tömböt ("programs") tartalmaz 1526 beágyazott JSON-struktúrával. Úgy van jsonArray beállítvaparsingMode, hogy az indexelő közölje, hogy minden blob tartalmaz egy JSON-tömböt. Mivel a beágyazott JSON egy szinttel lejjebb indul, állítsa be documentRoot a következőt /programs: .
Az indexelő néhány percig fut. Várjon, amíg az indexelő végrehajtása befejeződik, mielőtt bármilyen lekérdezést futtat.

Lekérdezések futtatása

Az első dokumentum betöltése után azonnal megkezdheti a keresést.

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

Küldje el a kérést. Ez egy meghatározatlan teljes szöveges keresési lekérdezés, amely az indexben lekérdezhetőként megjelölt mezőket és a dokumentumok számát adja vissza. A válasznak így kell kinéznie:

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

Adjon hozzá egy paramétert search a sztringben való kereséshez. Adjon hozzá egy paramétert select , amely kevesebb mezőre korlátozza az eredményeket. Adjon hozzá egy elemet filter a keresés további szűkítéséhez.

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

A válasz két dokumentumot ad vissza.

Szűrők esetén logikai operátorokat (és vagy nem) és összehasonlító operátorokat (eq, ne, gt, lt, ge, le) is használhat. A sztring-összehasonlítások megkülönböztetik a kis- és nagybetűket. További információkért és példákért lásd : Lekérdezés létrehozása.

Feljegyzés

A $filter paraméter csak az index létrehozásakor szűrhetőként megjelölt mezőkön működik.

Alaphelyzetbe állítás és ismételt futtatás

Az indexelőzmények alaphelyzetbe állíthatók, törölhetik a végrehajtási előzményeket, ami lehetővé teszi a teljes újrafuttatást. A következő GET-kérések alaphelyzetbe állításra, majd újrafuttatva jelennek meg.

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

Az erőforrások eltávolítása

Ha a saját előfizetésében dolgozik, a projekt végén célszerű eltávolítania a már nem szükséges erőforrásokat. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.

A portálon törölheti az indexeket, indexelőket és adatforrásokat.

Következő lépések

Most, hogy megismerte az Azure Blob-indexelés alapjait, tekintsük meg közelebbről az Indexelő konfigurációját az Azure Storage-ban található JSON-blobokhoz.

JSON-blobindexelés konfigurálása