Menambahkan, Memperbarui, atau Menghapus Dokumen (Azure AI Search REST API)
Anda dapat mengimpor dokumen pencarian ke dalam indeks tertentu menggunakan HTTP POST. Untuk pembaruan besar, batching (hingga 1000 dokumen per batch, atau sekitar 16 MB per batch) direkomendasikan dan akan secara signifikan meningkatkan performa pengindeksan.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Untuk sumber data Azure yang didukung, pengindeks menawarkan alternatif yang lebih sederhana untuk menambahkan dan memperbarui dokumen. Untuk informasi selengkapnya, lihatPengindeks.
Parameter URI
| Parameter | Deskripsi |
|---|---|
| nama layanan | Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda. |
| nama indeks | Diperlukan pada URI, menentukan indeks mana yang akan diposting dokumen. Anda hanya dapat memposting dokumen ke satu indeks pada satu waktu. |
| versi-api | Wajib diisi. Versi stabil saat ini adalah api-version=2020-06-30. Lihat versi API untuk versi lainnya. |
Judul Permintaan
Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.
| Bidang | Deskripsi |
|---|---|
| Jenis-Konten | Wajib diisi. Atur titik akhir ini ke application/json |
| api-key | Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Mengunggah dokumen memerlukan kunci API admin. Lihat Menyambungkan ke Pencarian Azure AI menggunakan autentikasi kunci untuk detailnya. |
Isi Permintaan
Isi permintaan berisi satu atau beberapa dokumen yang akan diindeks. Dokumen diidentifikasi oleh kunci peka huruf besar/kecil yang unik. Setiap dokumen dikaitkan dengan tindakan: "upload", "delete", "merge", atau "mergeOrUpload". Permintaan pengunggahan harus menyertakan data dokumen sebagai sekumpulan pasangan kunci/nilai.
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema)
...
},
...
]
}
| Properti | Deskripsi |
|---|---|
| @search.action | Wajib diisi. Nilai yang valid adalah "upload", "delete", "merge", atau "mergeOrUpload". Default ke "unggah". Anda dapat menggabungkan tindakan, satu per dokumen, dalam batch yang sama.
"upload": Tindakan unggahan mirip dengan 'upsert' di mana dokumen akan dimasukkan jika baru dan diperbarui/diganti jika ada. Semua bidang diganti dalam kasus pembaruan. "delete": Delete menghapus dokumen yang ditentukan dari indeks. Bidang apa pun yang Anda tentukan dalam operasi penghapusan, selain bidang kunci, akan diabaikan. Jika Anda ingin menghapus bidang individual dari dokumen, gunakan merge sebagai gantinya dan atur bidang secara eksplisit ke null.
"mergeOrUpload": Tindakan ini berakibat seperti penggabungan jika dokumen dengan kunci yang diberikan sudah ada dalam indeks. Jika dokumen tidak ada, dokumen ber perilaku seperti unggahan dengan dokumen baru. "merge": Gabungkan pembaruan dokumen yang ada dengan bidang yang ditentukan. Jika dokumen tidak ada, penggabungan gagal. Bidang apa pun yang Anda tentukan dalam gabungan akan menggantikan bidang yang sudah ada dalam dokumen. Ini juga berlaku untuk koleksi jenis primitif dan kompleks. Dalam koleksi primitif, jika dokumen berisi bidang Tag dari jenis Collection(Edm.String) dengan nilai ["budget"], dan Anda menjalankan penggabungan dengan nilai ["economy", "pool"] untuk Tag, nilai akhir bidang Tag akan menjadi ["economy", "pool"]. Ini tidak akan menjadi ["anggaran", "ekonomi", "kumpulan"]. 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 Rooms akan menjadi [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Ini tidak akan menjadi salah satu dari berikut ini: [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (append elements) [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (menggabungkan elemen secara berurutan, lalu menambahkan ekstra apa pun) |
| key_field_name | Wajib diisi. Definisi bidang dalam indeks yang berfungsi sebagai kunci dokumen dan hanya berisi nilai unik. Kunci dokumen hanya dapat berisi huruf, angka, tanda hubung ("-"), garis bawah ("_"), dan tanda sama dengan ("=") dan peka huruf besar/kecil. Untuk informasi selengkapnya, lihat Aturan penamaan. |
| field_name | Wajib diisi. Pasangan nama-nilai, di mana nama bidang sesuai dengan nama bidang dalam definisi indeks. Nilai ditentukan pengguna tetapi harus valid untuk jenis bidang. |
Catatan
Tidak ada jaminan pengurutan di mana tindakan dalam isi permintaan dijalankan terlebih dahulu. Tidak disarankan untuk memiliki beberapa tindakan "penggabungan" yang terkait dengan dokumen yang sama dalam satu isi permintaan. Jika ada beberapa tindakan "gabung" yang diperlukan untuk dokumen yang sama, lakukan penggabungan sisi klien sebelum memperbarui dokumen dalam indeks pencarian.
Respons
Kode status: 200 dikembalikan untuk respons yang berhasil, yang berarti bahwa semua item telah disimpan dengan tahan lama dan akan mulai diindeks. Pengindeksan berjalan di latar belakang dan membuat dokumen baru tersedia (yaitu, dapat dikueri dan dapat dicari) beberapa detik setelah operasi pengindeksan selesai. Penundaan khusus tergantung pada beban pada layanan.
Pengindeksan yang berhasil ditunjukkan oleh properti status yang diatur ke true untuk semua item, serta properti statusCode diatur ke 201 (untuk dokumen yang baru diunggah) atau 200 (untuk dokumen yang digabungkan atau dihapus):
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
Kode status: 207 dikembalikan ketika setidaknya satu item tidak berhasil diindeks. Item yang belum diindeks memiliki bidang status yang diatur ke false. Properti errorMessage dan statusCode menunjukkan alasan kesalahan pengindeksan:
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
Properti errorMessage menunjukkan alasan kesalahan pengindeksan jika memungkinkan.
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. Yang terakhir Anda harus mencoba kembali setelah penundaan.
| Kode status | Makna | Dapat Dicoba Lagi | Catatan |
|---|---|---|---|
| 200 | Dokumen berhasil diubah atau dihapus. | n/a | Operasi penghapusan adalah tidak dapat diubah. 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 | Ada 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 mereka membuat dokumen baru, dan tidak terjadi untuk penghapusan karena tidak idempotensi. |
| 409 | Konflik versi terdeteksi saat mencoba mengindeks dokumen. | Ya | Hal ini bisa terjadi ketika Anda mencoba mengindeks dokumen yang sama lebih dari satu kali secara bersamaan. |
| 422 | Indeks untuk sementara tidak tersedia karena diperbarui dengan bendera 'allowIndexDowntime' diatur ke 'true'. | Ya | |
| 503 | Layanan pencarian Anda untuk sementara tidak tersedia, mungkin karena beban berat. | Ya | Dalam kasus ini, kode Anda harus menunggu sebelum mencoba lagi atau Anda berisiko memperpanjang tidak tersedianya layanan. |
Catatan
Jika kode klien Anda sering mengalami respons 207, salah satu alasan yang mungkin adalah sistem sedang dimuat. 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.
Kode status: 429 menunjukkan bahwa Anda telah melebihi kuota Anda pada jumlah dokumen per indeks. Anda harus membuat indeks baru atau meningkatkan untuk batas kapasitas yang lebih tinggi.
Contoh
Contoh: Mengunggah dua dokumen yang sepenuhnya ditentukan
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
Catatan
Saat Anda mengunggah DateTimeOffset nilai dengan informasi zona waktu ke indeks Anda, Azure AI Search menormalkan nilai-nilai ini ke UTC. Misalnya, 2019-01-13T14:03:00-08:00 akan disimpan sebagai 2019-01-13T22:03:00Z. Jika Anda perlu menyimpan informasi zona waktu, Anda harus menambahkan kolom tambahan ke indeks Anda.