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

Azure Yapay Zeka Arama, 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, verilerin içindeki içeriği ayıran etiketler veya işaretler 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 öğreticide, REST istemcisi ve Arama REST API'lerini kullanarak iç içe JSON dizilerinin dizinini nasıl oluşturabileceğiniz gösterilmektedir:

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Ücretsiz hesap oluşturun.

• Azure Depolama

• Azure AI Arama. Geçerli aboneliğinizde bir hizmet oluşturun veya mevcut bir hizmeti bulun.

• Visual Studio Code ile bir REST istemcisi.

Dosyaları indirme

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

• ny filarmoni ücretsiz

Örnek veriler, bir JSON dizisi ve 1.521 iç içe JSON öğesi içeren tek bir JSON dosyasıdır. 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'ya yükleme

1. Azure Depolama'da ny-philharmonic-free adlı yeni bir kapsayıcı oluşturun.

2. Örnek veri dosyalarını karşıya yükleyin.

3. Azure Yapay Zeka Arama'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 Yapay Zeka Arama bağlantıları için bir uç nokta ve bir API anahtarı gereklidir. Bu değerleri Azure portalından alabilirsiniz. Alternatif bağlantı yöntemleri için bkz. Yönetilen kimlikler.

1. Azure portalında arama hizmetinize gidin.

2. Sol bölmeden Genel Bakış'ı seçin ve uç noktayı kopyalayın. Şu biçimde olmalıdır: https://my-service.search.windows.net

3. Sol bölmeden Ayarlar>Anahtarları'nı seçin ve hizmette tam haklar için bir yönetici anahtarı kopyalayın. İş sürekliliğini sağlamak için, birini değiştirmeniz gerektiğinde iki değiştirilebilir yönetici anahtarı sağlanmıştır. İsteklerde nesneleri eklemek, değiştirmek veya silmek için iki anahtardan birini kullanabilirsiniz.

   

REST dosyanızı ayarlama

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

2. İ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
   

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

REST istemcisiyle ilgili yardım için bkz . Hızlı Başlangıç: REST kullanarak tam metin arama.

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=2026-04-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name" : "ny-philharmonic-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnection}}"
        },
        "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://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net:443/datasources('ny-philharmonic-ds')?api-version=2026-04-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
}

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. Azure Yapay Zeka Arama şu anda iç içe JSON ile alan eşlemelerini desteklemediğinden alan adlarının ve veri türlerinin tamamen eşleşmesi gerekir. Aşağıdaki dizin ham içerikteki JSON öğelerine hizalanır.

### Create an index
POST {{baseUrl}}/indexes?api-version=2026-04-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, Collection(Edm.ComplextType) olarak 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=2026-04-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 her bloğun bir JSON dizisi içerdiğini söylemek için parsingModejsonArray olarak ayarlayın. İç içe JSON bir düzey aşağı başladığı için documentRoot değerini /programs olarak ayarlayın.

• 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=2026-04-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://<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=2026-04-01"
}

Dizede arama yapmak için bir search parametre, sonuçları daha az alanla sınırlamak için bir select parametre ve aramayı daha da daraltmak için bir filter parametre ekleyin.

### Query the index
POST {{baseUrl}}/indexes/ny-philharmonic-index/docs/search?api-version=2026-04-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 verilir.

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.

Sıfırla ve yeniden başlat

Indexleyiciler, yürütme geçmişini temizleyerek tam bir yeniden çalıştırmaya izin verecek şekilde sıfırlanabilir. Aşağıdaki POST 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=2026-04-01  HTTP/1.1
  api-key: {{apiKey}}

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

### Check indexer status 
GET {{baseUrl}}/indexers/ny-philharmonic-indexer/status?api-version=2026-04-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.

Dizinleri, dizin oluşturucuları ve veri kaynaklarını silmek için Azure portalını kullanabilirsiniz.

Sonraki adımlar

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