Memuat data ke dalam indeks pencarian di Pencarian Azure AI

Artikel ini menjelaskan cara mengimpor dokumen ke dalam indeks pencarian yang telah ditentukan sebelumnya menggunakan REST API, Azure SDK, atau portal Microsoft Azure.

Prasyarat

• Layanan Pencarian Azure AI (tingkat apa pun). Buat layanan atau temukan yang sudah ada.

• Indeks pencarian yang sudah ada. Artikel ini mengasumsikan Anda sudah membuat indeks. Jika Anda perlu membuat dan memuat dalam satu langkah, gunakan wizard impor atau pengindeks.

• Izin untuk memuat dokumen:

  • Autentikasi berbasis kunci: Kunci API admin untuk layanan pencarian Anda.
  • Autentikasi berbasis peran: Peran Kontributor Data Indeks Pencarian pada layanan pencarian.

• Untuk pengembangan SDK, instal pustaka klien Azure Search:

  • .NET: Azure. Search.Documents
  • Python: azure-search-documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Menggunakan portal Azure

Di portal Microsoft Azure, gunakan wizard impor untuk membuat dan memuat indeks dalam alur kerja yang mulus. Jika Anda ingin memuat indeks yang ada, pilih pendekatan alternatif.

1. Buka layanan pencarian Anda di portal Microsoft Azure.

2. Pada halaman Gambaran Umum , pilih Impor data pada bilah perintah untuk membuat dan mengisi indeks pencarian.

   

   Anda dapat mengikuti tautan ini untuk meninjau alur kerja: Mulai Cepat: Membuat indeks Pencarian Azure AI dan Mulai Cepat: Vektorisasi terintegrasi.

3. Setelah panduan selesai, gunakan Search Explorer untuk memeriksa hasil.

Menggunakan REST API

Dokumen - Indeks adalah REST API untuk mengimpor data ke dalam indeks pencarian.

Isi permintaan berisi satu atau beberapa dokumen yang akan diindeks. Identitas dokumen secara unik ditentukan melalui kunci yang peka terhadap huruf besar/kecil. Setiap dokumen dikaitkan dengan tindakan: "upload", "delete", "merge", atau "mergeOrUpload". Permintaan pengunggahan harus menyertakan data dokumen sebagai sekumpulan pasangan kunci/nilai.

REST API berguna untuk pengujian bukti konsep awal, di mana Anda dapat menguji alur kerja pengindeksan tanpa harus menulis banyak kode. Parameter @search.action menentukan apakah dokumen ditambahkan secara penuh, atau sebagian dalam hal nilai baru atau penggantian untuk bidang tertentu.

Mulai cepat: Pencarian teks lengkap menggunakan REST menjelaskan langkah-langkahnya . Contoh berikut adalah versi contoh yang dimodifikasi. Untuk kejelasan, nilai dipangkas dan nilai HotelId pertama diubah agar dapat menghindari penggantian dokumen yang sudah ada.

1. Rumuskan panggilan POST yang menentukan nama indeks, titik akhir "docs/index", dan isi permintaan yang menyertakan @search.action parameter .

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2026-04-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Atur @search.action parameter ke upload untuk membuat atau menimpa dokumen. Atur ke merge atau uploadOrMerge jika Anda menargetkan pembaruan ke bidang tertentu dalam dokumen. Contoh sebelumnya menunjukkan kedua tindakan.

   Perbuatan	Efek
   pengunggahan	Mirip dengan "upsert" di mana dokumen disisipkan jika baru, dan diperbarui atau diganti jika sudah ada. Jika dokumen kehilangan nilai yang diperlukan indeks, nilai bidang dokumen diatur ke null.
   gabung	Memperbarui dokumen yang sudah ada, dan memberikan kesalahan jika dokumen tidak dapat ditemukan. Gabung menggantikan nilai yang ada. Untuk alasan ini, pastikan untuk memeriksa bidang koleksi yang berisi beberapa nilai, seperti bidang jenis Collection(Edm.String). Misalnya, jika tags dimulai dengan nilai ["budget"] dan Anda menjalankan penggabungan dengan ["economy", "pool"], nilai akhir dari tags adalah ["economy", "pool"]. Ini bukan ["budget", "economy", "pool"].
   gabungAtauUnggah	Bertindak seperti penggabungan jika dokumen sudah ada, dan unggah jika dokumen tersebut baru. Ini adalah tindakan paling umum untuk pembaruan inkremental.
   hapus	"Menghapus dokumen yang ditentukan dari indeks." Bidang apa pun yang Anda tentukan dalam operasi penghapusan, selain bidang kunci, diabaikan. Jika Anda ingin menghapus bidang individual dari dokumen, gunakan gabungkan sebagai gantinya dan atur bidang secara eksplisit ke null. Untuk informasi selengkapnya, lihat Menghapus dokumen dalam indeks pencarian.

   Tidak ada jaminan bahwa tindakan dalam isi permintaan akan dieksekusi sesuai urutan. Tidak disarankan untuk memiliki beberapa tindakan "gabungkan" yang terkait dengan dokumen yang sama dalam satu isi permintaan. Jika ada beberapa tindakan "gabungkan" yang diperlukan untuk dokumen yang sama, lakukan penggabungan sisi klien sebelum memperbarui dokumen dalam indeks pencarian.

   Dalam koleksi primitif, jika dokumen berisi bidang jenis Collection(Edm.String) Tag dengan nilai ["anggaran"], dan Anda menjalankan penggabungan dengan nilai ["ekonomi", "kumpulan"] untuk Tag, nilai akhir bidang Tag akan menjadi ["ekonomi", "kumpulan"]. Ini bukan ["anggaran", "ekonomi", "kolam"].

   Dalam koleksi kompleks, jika dokumen berisi bidang koleksi kompleks bernama Rooms dengan nilai [{ "Type": "Budget Room", "BaseRate": 75.0 }], dan Anda menjalankan penggabungan dengan nilai [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], nilai akhir bidang Kamar akan menjadi [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ini tidak akan menjadi salah satu dari yang berikut ini:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (menambahkan elemen)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (gabungkan elemen secara berurutan, lalu tambahkan ekstra apa pun)

   Nota

   Saat Anda mengunggah nilai DateTimeOffset dengan informasi zona waktu ke indeks Anda, Pencarian Azure AI menormalkan nilai-nilai ini ke UTC. Misalnya, 2025-01-13T14:03:00-08:00 akan disimpan sebagai 2025-01-13T22:03:00Z. Jika Anda perlu menyimpan informasi zona waktu, tambahkan kolom tambahan ke indeks Anda.

3. Kirim permintaan.

   Tabel berikut menjelaskan berbagai kode status per dokumen yang dapat dikembalikan dalam respons. Beberapa kode status menunjukkan masalah dengan permintaan itu sendiri, sementara yang lain menunjukkan kondisi kesalahan sementara. Pilihan terakhir yang harus Anda coba lagi setelah jeda.

   Kode status	Meaning	Dapat Dicoba Lagi	Catatan
   200	Dokumen berhasil diubah atau dihapus.	n/a	Operasi penghapusan adalah idempoten. Artinya, bahkan jika kunci dokumen tidak ada dalam indeks, mencoba operasi penghapusan dengan kunci tersebut menghasilkan kode status 200.
   201	Dokumen berhasil dibuat.	n/a
   400	Terjadi kesalahan dalam dokumen yang mencegahnya diindeks.	Tidak.	Pesan kesalahan dalam respons menunjukkan apa yang salah dengan dokumen.
   404	Dokumen tidak dapat digabungkan karena kunci yang diberikan tidak ada dalam indeks.	Tidak.	Kesalahan ini tidak terjadi untuk unggahan karena unggahan membuat dokumen baru, dan tidak terjadi untuk penghapusan karena idempoten.
   409	Konflik versi terdeteksi saat mencoba mengindeks dokumen.	Yes	Hal ini bisa terjadi ketika Anda mencoba mengindeks dokumen yang sama lebih dari satu kali secara bersamaan.
   422	Indeks sementara tidak tersedia karena diperbarui dengan bendera 'allowIndexDowntime' diatur ke 'true'.	Yes
   429	Menunjukkan bahwa Anda telah melebihi kuota Anda pada jumlah dokumen per indeks.	Tidak.	Anda harus membuat indeks baru atau meningkatkan untuk batas kapasitas yang lebih tinggi.
   503	Layanan pencarian Anda untuk sementara tidak tersedia, mungkin karena beban berat.	Yes	Dalam kasus ini, kode Anda harus menunggu sebelum mencoba lagi atau Anda berisiko memperpanjang tidak tersedianya layanan.

   Nota

   Jika kode klien Anda sering menerima respons 207, salah satu alasan yang mungkin adalah sistem sedang mengalami beban. Anda dapat mengonfirmasi ini dengan memeriksa statusCode properti untuk 503. Jika demikian, sebaiknya batasi permintaan pengindeksan. Jika tidak, jika lalu lintas pengindeksan tidak mereda, sistem dapat mulai menolak semua permintaan dengan kesalahan 503.

4. Periksa dokumen yang baru saja Anda tambahkan sebagai langkah untuk validasi.

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2026-04-01
   

Referensi:Dokumen - Indeks, Dokumen - Dapatkan

Permintaan indeks yang berhasil mengembalikan HTTP 200 (OK) untuk batch di mana semua dokumen berhasil, atau HTTP 207 (Multi-Status) jika beberapa dokumen gagal. Isi respons berisi status untuk setiap dokumen:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Ketika kunci dokumen atau ID baru, null menjadi nilai untuk bidang apa pun yang tidak ditentukan dalam dokumen. Untuk tindakan pada dokumen yang sudah ada, nilai yang diperbarui akan menggantikan nilai sebelumnya. Bidang apa pun yang tidak ditentukan dalam "gabungkan" atau "mergeUpload" dibiarkan utuh dalam indeks pencarian.

Menggunakan Azure SDK

Kemampuan pemrograman disediakan dalam Azure SDK berikut.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Memverifikasi pemuatan data Anda

Setelah memuat dokumen, verifikasi bahwa data diindeks dengan benar.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2026-04-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Cara kerja impor data

Layanan pencarian menerima dokumen JSON yang sesuai dengan skema indeks. Layanan pencarian dapat mengimpor dan mengindeks konten teks biasa dan konten vektor dalam dokumen JSON.

• Konten teks polos diambil dari bidang di sumber data eksternal, dari properti metadata, atau dari konten yang diperkaya yang dihasilkan oleh skillset. Keterampilan dapat mengekstrak atau menyimpulkan deskripsi tekstual dari gambar dan konten yang tidak terstruktur.

• Konten vektor diambil dari sumber data yang menyediakannya, atau dibuat oleh set keterampilan yang menerapkan vektorisasi terintegrasi dalam beban kerja pengindeks Pencarian Azure AI.

Anda dapat menyiapkan dokumen ini sendiri, tetapi jika konten berada di sumber data yang didukung, menjalankan pengindeks atau menggunakan wizard impor dapat mengotomatiskan pengambilan dokumen, serialisasi JSON, dan pengindeksan.

Setelah data diindeks, struktur data indeks fisik dikunci. Untuk panduan tentang apa yang dapat dan tidak dapat diubah, lihat Memperbarui dan membangun kembali indeks.

Pengindeksan bukan proses latar belakang. Layanan pencarian menyeimbangkan beban kerja pengindeksan dan kueri, tetapi jika latensi kueri terlalu tinggi, Anda dapat menambahkan kapasitas atau mengidentifikasi periode aktivitas kueri rendah untuk memuat indeks.

Untuk informasi selengkapnya, lihat Strategi impor data.

Memecahkan masalah kesalahan umum