Öğretici: REST kullanarak Azure Depolama iç içe JSON bloblarını dizine alma

Makale
03/15/2024

Azure AI Search, yarı yapılandırılmış verilerin nasıl okunduğunu bilen bir dizin oluşturucu kullanarak Azure Blob Depolama JSON belgelerinin ve dizilerinin dizinini oluşturabilir. Yarı yapılandırılmış veriler, veriler içindeki içeriği ayıran etiketleri veya işaretleri içerir. Tamamen dizine alınması gereken yapılandırılmamış veriler ile alan başına dizine alınabilen ilişkisel veritabanı şeması gibi bir veri modeline bağlı olan resmi olarak yapılandırılmış veriler arasındaki farkı böler.

Bu öğretici, iç içe JSON dizilerinin dizinini oluşturmanızı gösterir. Aşağıdaki görevleri gerçekleştirmek için bir REST istemcisi ve Search REST API'leri kullanır:

Örnek verileri ayarlama ve veri azureblob kaynağını yapılandırma
Aranabilir içerik içerecek bir Azure AI Arama dizini oluşturma
Kapsayıcıyı okumak ve aranabilir içeriği ayıklamak için dizin oluşturucu oluşturma ve çalıştırma
Oluşturduğunuz dizini arama

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

REST istemcisi ile Visual Studio Code.
Azure Depolama
Azure AI Arama. Geçerli aboneliğinizin altında mevcut bir Azure AI Search kaynağı oluşturun veya bulun.

Not

Bu öğretici için ücretsiz hizmeti kullanabilirsiniz. Ücretsiz arama hizmeti sizi üç dizin, üç dizin oluşturucu ve üç veri kaynağıyla sınırlar. Bu öğreticide hepsinden birer tane oluşturulur. Başlamadan önce, hizmetinizde yeni kaynakları kabul etmek için yer olduğundan emin olun.

Dosyaları indirme

Örnek veri deposunun zip dosyasını indirin ve içeriğini ayıklayın. Nasıl olduğunu öğrenin.

ny-filarmonisiz

Örnek veriler, bir JSON dizisi ve 1.521 iç içe JSON öğesi içeren tek bir JSON dosyasıdır. Örnek veriler Kaggle'da NY Filarmoni Performans Geçmişi'nden kaynaklanır. Ücretsiz katmanın depolama sınırları altında kalmak için bir JSON dosyası seçtik.

İşte dosyadaki ilk iç içe JSON. Dosyanın geri kalanı 1.520 konser performansı örneği daha içerir.

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

Örnek verileri Azure Depolama'a yükleme

Azure Depolama'da yeni bir kapsayıcı oluşturun ve bunu ny-filarmonisiz olarak adlandırın.
Örnek veri dosyalarını karşıya yükleyin.
Azure AI Search'te bağlantı formüle edebilmeniz için depolama bağlantı dizesi alın.
1. Sol tarafta Erişim anahtarları'nı seçin.
2. Birinci veya ikinci anahtar için bağlantı dizesi kopyalayın. bağlantı dizesi aşağıdaki örneğe benzer:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Arama hizmeti URL'si ve API anahtarı kopyalama

Bu öğretici için Azure AI Search bağlantıları için bir uç nokta ve bir API anahtarı gerekir. Bu değerleri Azure portalından alabilirsiniz.

Azure portalında oturum açın, arama hizmetine Genel Bakış sayfasına gidin ve URL'yi kopyalayın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.
Ayarlar> Keys altında bir yönetici anahtarı kopyalayın. Yönetici anahtarları nesneleri eklemek, değiştirmek ve silmek için kullanılır. Değiştirilebilir iki yönetici anahtarı vardır. İkisini de kopyalayın.

REST dosyanızı ayarlama

Visual Studio Code'u başlatın ve yeni bir dosya oluşturun

İstekte kullanılan değişkenler için değerler sağlayın:

@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

Veya .http dosya uzantısını kullanarak .rest dosyayı kaydedin.

REST istemcisiyle ilgili yardıma ihtiyacınız varsa bkz . Hızlı Başlangıç: REST kullanarak metin araması.

Veri kaynağı oluşturma

Veri Kaynağı Oluştur (REST), hangi verilerin dizine alınacağını belirten bir veri kaynağı bağlantısı oluşturur.

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

İsteği gönderin. Yanıt şöyle görünmelidir:

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
}

Dizin oluşturma

Dizin Oluştur (REST), arama hizmetinizde bir arama dizini oluşturur. Dizin, tüm parametreleri ve parametrelerin özniteliklerini belirtir.

İç içe JSON için dizin alanlarının kaynak alanlarla aynı olması gerekir. Şu anda Azure AI Search, iç içe JSON ile alan eşlemelerini desteklememektedir. Bu nedenle, alan adları ve veri türleri tamamen eşleşmelidir. Aşağıdaki dizin ham içerikteki JSON öğelerine hizalanır.

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

Önemli noktalar:

Alan adlarındaki veya veri türlerindeki farkları mutabık hale getirmek için alan eşlemelerini kullanamazsınız. Bu dizin şeması ham içeriği yansıtacak şekilde tasarlanmıştır.
İç içe JSON olarak Collection(Edm.ComplextType)modellenmiştir. Ham içerikte, her sezon için birden fazla konser ve her konser için birden fazla çalışma vardır. Bu yapıya uyum sağlamak için karmaşık türler için koleksiyonları kullanın.
Ham içerikte Date ve Time dizeler olduğundan, dizindeki ilgili veri türleri de dizelerdir.

Dizin oluşturucu oluşturma ve çalıştırma

Dizin Oluşturucu Oluştur, arama hizmetinizde bir dizin oluşturucu oluşturur. Dizin oluşturucu veri kaynağına bağlanır, verileri yükler ve dizinler ve isteğe bağlı olarak veri yenilemeyi otomatikleştirmek için bir zamanlama sağlar.

Dizin oluşturucu yapılandırması jsonArray ayrıştırma modunu ve bir documentRootiçerir.

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

Önemli noktalar:

Ham içerik dosyası, 1.526 iç içe JSON yapısına sahip bir JSON dizisi ("programs") içerir. Dizin oluşturucuya jsonArray her blobunun bir JSON dizisi içerdiğini söylemek için olarak ayarlayınparsingMode. İç içe JSON bir düzey aşağı başladığı için olarak ayarlayın documentRoot/programs.
Dizin oluşturucu birkaç dakika boyunca çalışır. Sorgu çalıştırmadan önce dizin oluşturucu yürütme işleminin tamamlanmasını bekleyin.

Sorgu çalıştırma

İlk belge yüklenir yüklenmez aramaya başlayabilirsiniz.

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

İsteği gönderin. Bu, dizinde alınabilir olarak işaretlenmiş tüm alanları ve belge sayısını döndüren, belirtilmemiş bir tam metin arama sorgusudur. Yanıt şöyle görünmelidir:

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

Bir search dizede aramak için bir parametre ekleyin. Sonuçları daha az alanla sınırlamak için bir select parametre ekleyin. Aramayı daha da daraltmak için bir filter ekleyin.

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

Yanıtta iki belge döndürülür.

Filtreler için Mantıksal işleçleri (ve veya değil) ve karşılaştırma işleçlerini (eq, ne, gt, lt, ge, le) de kullanabilirsiniz. Dize karşılaştırmaları büyük/küçük harfe duyarlıdır. Daha fazla bilgi ve örnek için bkz . Sorgu oluşturma.

Not

$filter parametresi yalnızca dizininizin oluşturulması sırasında filtrelenebilir olarak işaretlenmiş alanlarda çalışır.

Sıfırlama ve yeniden çalıştırma

Dizin oluşturucular sıfırlanabilir ve tam yeniden çalıştırmaya izin veren yürütme geçmişi temizlenebilir. Aşağıdaki GET istekleri sıfırlamaya yöneliktir ve ardından yeniden çalıştırılır.

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

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, bir projenin sonunda artık ihtiyacınız olmayan kaynakları kaldırmak iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.

Portalı kullanarak dizinleri, dizin oluşturucuları ve veri kaynaklarını silebilirsiniz.

Sonraki adımlar

Artık Azure Blob dizin oluşturmanın temellerini bildiğinize göre, Azure Depolama'de JSON blobları için dizin oluşturucu yapılandırmasına daha yakından bakalım.

JSON blob dizini oluşturmayı yapılandırma