Tutorial: Mengindeks blob JSON berlapis dari Azure Storage menggunakan REST

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 untuk mengindeks array JSON berlapis. Ini menggunakan klien REST dan REST API Pencarian untuk melakukan tugas-tugas berikut:

  • 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

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

Catatan

Anda dapat menggunakan layanan gratis untuk tutorial ini. Layanan pencarian gratis membatasi Anda hingga tiga indeks, tiga pengindeks, dan tiga sumber data. Tutorial ini membuat satu layanan dari masing-masing layanan. 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.

Data sampel adalah satu file JSON yang berisi array JSON dan 1.521 elemen JSON berlapis. Data sampel 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. Sisa file mencakup 1.520 instans 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

  1. Di Azure Storage, buat kontainer baru dan beri nama ny-philharmonic-free.

  2. Unggah file data sampel.

  3. 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 dua kunci. 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.

  1. Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum layanan pencarian, dan salin URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.

  2. Di bawah Pengaturan> Keys, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

    Screenshot of the URL and API keys in the Azure portal.

Menyiapkan file REST Anda

  1. Mulai Visual Studio Code dan buat file baru

  2. 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
    
  3. Simpan file menggunakan .rest ekstensi file atau .http .

Lihat Mulai Cepat: Pencarian teks menggunakan REST jika Anda memerlukan bantuan dengan klien 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=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
    }

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://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
}

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. Untuk alasan ini, nama bidang dan jenis data harus sama sepenuhnya. Indeks berikut selaras dengan elemen JSON dalam konten mentah.

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

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 jenis 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 jsonArray mode penguraian dan 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" : [ 
      ]
    }

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 memulai 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=2023-11-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://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"
}

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

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

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 tidak peka huruf besar/kecil. Untuk informasi dan contoh selengkapnya, lihat Membuat kueri.

Catatan

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

Atur ulang dan jalankan ulang

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

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

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 menghabiskan 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 untuk menghapus indeks, pengindeks, dan sumber data.

Langkah berikutnya

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