Zelfstudie: Geneste JSON-blobs indexeren vanuit Azure Storage met behulp van REST

Artikel
09/01/2024

Azure AI Search kan JSON-documenten en -matrices indexeren in Azure Blob Storage met behulp van een indexeerfunctie die weet hoe semi-gestructureerde gegevens moeten worden gelezen. Semi-gestructureerde gegevens bevatten labels of markeringen die inhoud in de gegevens scheiden. Het splitst het verschil tussen ongestructureerde gegevens, die volledig moeten worden geïndexeerd en formeel gestructureerde gegevens die voldoen aan een gegevensmodel, zoals een relationeel databaseschema dat per veld kan worden geïndexeerd.

In deze zelfstudie ziet u hoe u geneste JSON-matrices indexeert. Er wordt gebruikgemaakt van een REST-client en de SEARCH REST API's om de volgende taken uit te voeren:

Voorbeeldgegevens instellen en een azureblob gegevensbron configureren
Een Azure AI Search-index maken om doorzoekbare inhoud te bevatten
Een indexeerfunctie maken en uitvoeren om de container te lezen en doorzoekbare inhoud te extraheren
De index doorzoeken die u zojuist hebt gemaakt

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Visual Studio Code met een REST-client.
Azure Storage
Azure AI Search. Maak of zoek een bestaande Azure AI Search-resource onder uw huidige abonnement.

Notitie

U kunt de gratis service voor deze zelfstudie gebruiken. Een gratis zoekservice beperkt u tot drie indexen, drie indexeerfuncties en drie gegevensbronnen. In deze zelfstudie wordt één exemplaar van elk onderdeel gemaakt. Voordat u aan de slag gaat, zorg ervoor dat uw service voldoende ruimte heeft voor de nieuwe resources.

Bestanden downloaden

Download een zip-bestand van de opslagplaats met voorbeeldgegevens en pak de inhoud uit. Meer informatie.

ny-philharmonisch-vrij

Voorbeeldgegevens zijn één JSON-bestand met een JSON-matrix en 1521 geneste JSON-elementen. Voorbeeldgegevens zijn afkomstig uit ny Philharmonische prestatiegeschiedenis op Kaggle. We hebben één JSON-bestand gekozen om onder de opslaglimieten van de gratis laag te blijven.

Dit is de eerste geneste JSON in het bestand. De rest van het bestand bevat 1520 andere exemplaren van concertvoorstellingen.

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

Voorbeeldgegevens uploaden naar Azure Storage

Maak in Azure Storage een nieuwe container en geef deze een nieuwe naam zonder philharmonische naam.
Upload de voorbeeldgegevensbestanden.
Haal een opslag verbindingsreeks zodat u een verbinding kunt formuleren in Azure AI Search.
1. Selecteer aan de linkerkant Toegangssleutels.
2. Kopieer de verbindingsreeks voor sleutel één of twee. De verbindingsreeks is vergelijkbaar met het volgende voorbeeld:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Een URL en API-sleutel van een zoekservice kopiëren

Voor deze zelfstudie is voor verbindingen met Azure AI Search een eindpunt en een API-sleutel vereist. U kunt deze waarden ophalen uit Azure Portal.

Meld u aan bij Azure Portal, navigeer naar de overzichtspagina van de zoekservice en kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Kopieer onder Instellingensleutels> een beheerderssleutel. Beheerderssleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

Uw REST-bestand instellen

Visual Studio Code starten en een nieuw bestand maken

Geef waarden op voor variabelen die in de aanvraag worden gebruikt:

@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

Sla het bestand op met behulp van een .rest of .http bestandsextensie.

Zie quickstart: Tekst zoeken met REST als u hulp nodig hebt bij de REST-client.

Een gegevensbron maken

Een gegevensbronverbinding maken (REST) maakt een gegevensbronverbinding waarmee wordt aangegeven welke gegevens moeten worden geïndexeert.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-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
    }

Verzend de aanvraag. Het antwoord moet er als volgt uitzien:

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://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net:443/datasources('ny-philharmonic-ds')?api-version=2024-07-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://<YOUR-SEARCH-SERVICE-NAME>.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
}

Een index maken

Index maken (REST) maakt een zoekindex voor uw zoekservice. Een index geeft alle parameters en hun kenmerken op.

Voor geneste JSON moeten de indexvelden identiek zijn aan de bronvelden. Momenteel biedt Azure AI Search geen ondersteuning voor veldtoewijzingen voor geneste JSON. Daarom moeten veldnamen en gegevenstypen volledig overeenkomen. De volgende index wordt uitgelijnd op de JSON-elementen in de onbewerkte inhoud.

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-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 }
          ]
        }
      ]
    }

Belangrijkste punten:

U kunt veldtoewijzingen niet gebruiken om verschillen in veldnamen of gegevenstypen af te stemmen. Dit indexschema is ontworpen om de onbewerkte inhoud te spiegelen.
Geneste JSON is gemodelleerd als Collection(Edm.ComplextType). In de onbewerkte inhoud zijn er meerdere concerten voor elk seizoen en meerdere werken voor elk concert. Gebruik verzamelingen voor complexe typen om deze structuur aan te passen.
In de onbewerkte inhoud Date en Time tekenreeksen zijn tekenreeksen, dus de bijbehorende gegevenstypen in de index zijn ook tekenreeksen.

Indexeerfunctie maken en uitvoeren

Indexeerfunctie maken maakt een indexeerfunctie voor uw zoekservice. Een indexeerfunctie maakt verbinding met de gegevensbron, laadt en indexeert gegevens en biedt desgewenst een planning voor het automatiseren van de gegevensvernieuwing.

De configuratie van de indexeerfunctie bevat de jsonArray parseringsmodus en een documentRoot.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-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" : [ 
      ]
    }

Belangrijkste punten:

Het onbewerkte inhoudsbestand bevat een JSON-matrix ("programs") met 1526 geneste JSON-structuren. Stel parsingMode deze in om de indexeerfunctie te jsonArray laten weten dat elke blob een JSON-matrix bevat. Omdat de geneste JSON één niveau omlaag start, ingesteld documentRoot op /programs.
De indexeerfunctie wordt enkele minuten uitgevoerd. Wacht totdat de uitvoering van de indexeerfunctie is voltooid voordat u query's uitvoert.

Query's uitvoeren

Zodra het eerste document is geladen, kunt u meteen beginnen met zoeken.

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

Verzend de aanvraag. Dit is een niet-opgegeven query voor zoeken op volledige tekst waarmee alle velden worden opgehaald die als Kan worden opgehaald zijn gemarkeerd in de index, samen met het aantal documenten. Het antwoord moet er als volgt uitzien:

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://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes('ny-philharmonic-index')/$metadata#docs(*)",
  "@odata.count": 1521,
  "@search.nextPageParameters": {
    "search": "*",
    "count": true,
    "skip": 50
  },
  "value": [
  ],
  "@odata.nextLink": "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/ny-philharmonic-index/docs/search?api-version=2024-07-01"
}

Voeg een search parameter toe om te zoeken op een tekenreeks. Voeg een select parameter toe om de resultaten te beperken tot minder velden. Voeg een filter toe om de zoekopdracht verder te verfijnen.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2024-07-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'"
  }

Er worden twee documenten geretourneerd in het antwoord.

Voor filters kunt u ook logische operatoren (en, of niet) en vergelijkingsoperators (eq, ne, gt, lt, ge, le) gebruiken. Tekenreeksvergelijkingen zijn hoofdlettergevoelig. Zie Een query maken voor meer informatie en voorbeelden.

Notitie

De $filter parameter werkt alleen op velden die zijn gemarkeerd als filterbaar bij het maken van uw index.

Opnieuw instellen en uitvoeren

Indexeerfuncties kunnen opnieuw worden ingesteld, uitvoeringsgeschiedenis wissen, waardoor een volledige uitvoering mogelijk is. De volgende GET-aanvragen zijn voor het opnieuw instellen, gevolgd door opnieuw uitvoeren.

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

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

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

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog steeds nodig hebt en of u deze moet verwijderen. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt de portal gebruiken om indexen, indexeerfuncties en gegevensbronnen te verwijderen.

Volgende stappen

Nu u bekend bent met de basisprincipes van het indexeren van Azure-blobs, gaan we de configuratie van de indexeerfunctie voor JSON-blobs in Azure Storage nader bekijken.

Het indexeren van JSON-blobs configureren

Share via