Tutorial: Mengindeks blob JSON berlapis dari Azure Storage menggunakan REST

2025-04-09

Azure AI Search dapat mengindeks dokumen dan array JSON di Azure Blob Storage menggunakan pengindeks yang tahu cara membaca data semi terstruktur. Data semi-terstruktur berisi tag atau tanda yang memisahkan konten dalam data. Ini membagi perbedaan antara data yang tidak terstruktur, yang harus sepenuhnya diindeks, dan data terstruktur secara resmi yang mematuhi model data, seperti skema database relasional yang dapat diindeks berdasarkan per bidang.

Tutorial ini menunjukkan kepada Anda cara mengindeks array JSON berlapis, menggunakan klien REST dan REST API Pencarian untuk:

Menyiapkan data sampel dan mengonfigurasi azureblob sumber data
Membuat indeks Pencarian Azure AI untuk berisi konten yang dapat dicari
Membuat dan menjalankan pengindeks untuk membaca kontainer dan mengekstrak konten yang dapat dicari
Mencari indeks yang baru saja Anda buat

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Azure Storage.
Pencarian Azure AI. Buat layanan atau temukan layanan yang sudah ada di langganan Anda saat ini.
Visual Studio Code dengan klien REST.

Catatan

Anda dapat menggunakan layanan pencarian gratis untuk tutorial ini. Tingkat Gratis membatasi Anda ke tiga indeks, tiga pengindeks, dan tiga sumber data. Tutorial ini membuat satu dari masing-masing. Sebelum memulai, pastikan Anda memiliki ruang pada layanan Anda untuk menerima sumber daya baru.

Mengunduh file

Unduh file zip dari repositori data sampel dan ekstrak kontennya. Pelajari caranya.

ny-philharmonic-free

Data sampel adalah satu file JSON yang berisi array JSON dan 1.521 elemen JSON berlapis. Data berasal dari Riwayat Performa NY Philharmonic di Kaggle. Kami memilih satu file JSON untuk tetap berada di bawah batas penyimpanan tingkat Gratis.

Berikut adalah JSON berlapis pertama dalam file. Sisanya dari file ini mencakup 1.520 contoh pertunjukan konser lainnya.

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

Mengunggah data sampel ke Azure Storage

Di Azure Storage, buat kontainer baru bernama ny-philharmonic-free.
Unggah data sampel file.
Dapatkan string koneksi penyimpanan sehingga Anda bisa merumuskan koneksi di Azure AI Search.
1. Di sebelah kiri, pilih Tombol akses.
2. Salin string koneksi untuk kunci satu atau kunci dua. string koneksi mirip dengan contoh berikut:
```
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
```

Menyalin URL layanan pencarian dan kunci API

Untuk tutorial ini, koneksi ke Azure AI Search memerlukan titik akhir dan kunci API. Anda bisa mendapatkan nilai-nilai ini dari portal Azure. Untuk metode koneksi alternatif, lihat Identitas terkelola.

Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum layanan pencarian, dan salin URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.
Di bawah Kunci Pengaturan>, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

Menyiapkan file REST Anda

Mulai Visual Studio Code dan buat file baru.

Berikan nilai untuk variabel yang digunakan dalam permintaan.

@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

Simpan file menggunakan .rest ekstensi file atau .http .

Untuk bantuan dengan klien REST, lihat Mulai Cepat: Pencarian teks lengkap menggunakan REST.

Membuat sumber data

Buat Sumber Data (REST) membuat koneksi sumber data yang menentukan data apa yang akan diindeks.

### 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": "{{storageConnection}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Kirim permintaan. Respons akan terlihat seperti ini:

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
}

Buat indeks

Buat Indeks (REST) membuat indeks pencarian di layanan pencarian Anda. Indeks menentukan semua parameter dan atributnya.

Untuk JSON berlapis, bidang indeks harus identik dengan bidang sumber. Saat ini, Azure AI Search tidak mendukung pemetaan bidang ke JSON berlapis, sehingga nama bidang dan jenis data harus sama sekali. Indeks berikut selaras dengan elemen JSON dalam konten mentah.

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

Poin utama:

Anda tidak dapat menggunakan pemetaan bidang untuk mendamaikan perbedaan dalam nama bidang atau jenis data. Skema indeks ini dirancang untuk mencerminkan konten mentah.
JSON berlapis dimodelkan sebagai Collection(Edm.ComplextType). Dalam konten mentah, ada beberapa konser untuk setiap musim, dan beberapa karya untuk setiap konser. Untuk mengakomodasi struktur ini, gunakan koleksi untuk tipe data kompleks.
Dalam konten mentah, Date dan Time merupakan string, sehingga jenis data yang sesuai dalam indeks juga merupakan string.

Membuat dan menjalankan pengindeks

Buat Pengindeks membuat pengindeks di layanan pencarian Anda. Pengindeks tersambung ke sumber data, memuat dan mengindeks data, dan secara opsional menyediakan jadwal untuk mengotomatiskan refresh data.

Konfigurasi pengindeks mencakup mode pemrosesan jsonArray dan 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" : [ 
      ]
    }

Poin utama:

File konten mentah berisi array JSON ("programs") dengan 1.526 struktur JSON berlapis. Atur parsingMode ke jsonArray untuk memberi tahu pengindeks bahwa setiap blob berisi array JSON. Karena JSON berlapis dimulai satu tingkat ke bawah, atur documentRoot ke /programs.
Pengindeks berjalan selama beberapa menit. Tunggu hingga eksekusi pengindeks selesai sebelum menjalankan kueri apa pun.

Jalankan Kueri

Anda dapat mulai mencari segera setelah dokumen pertama dimuat.

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

Kirim permintaan. Ini adalah kueri pencarian teks lengkap yang tidak ditentukan yang mengembalikan semua bidang yang ditandai sebagai dapat diambil dalam indeks, bersama dengan jumlah dokumen. Respons akan terlihat seperti ini:

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

Tambahkan parameter search untuk mencari pada string, parameter select untuk membatasi hasil ke lebih sedikit bidang, dan parameter filter untuk mempersempit pencarian lebih lanjut.

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

Dua dokumen dikembalikan dalam respons.

Untuk filter, Anda juga dapat menggunakan operator Logis (dan, atau, tidak) dan operator perbandingan (eq, ne, gt, lt, ge, le). Perbandingan string bersifat sensitif terhadap huruf besar dan kecil. Untuk informasi dan contoh selengkapnya, lihat Membuat kueri.

Catatan

Parameter $filter hanya berfungsi pada bidang yang ditandai dapat difilter selama pembuatan indeks.

Atur ulang dan jalankan ulang

Pengindeks dapat diatur ulang untuk menghapus riwayat eksekusi, yang memungkinkan pengoperasian ulang penuh. Permintaan POST berikut adalah untuk reset, diikuti dengan jalankan ulang.

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

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, di akhir proyek, sebaiknya hapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat memboroskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.

Anda dapat menggunakan portal Azure untuk menghapus indeks, pengindeks, dan sumber data.

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan dasar-dasar pengindeksan Azure Blob, lihat lebih dekat konfigurasi pengindeks untuk blob JSON di Azure Storage:

Konfigurasikan pengindeksan blob JSON