Belge Ekleme, Güncelleştirme veya Silme (Azure AI Arama REST API'si)
HTTP POST kullanarak arama belgelerini belirtilen dizine aktarabilirsiniz . Büyük bir güncelleştirme için toplu işlem (toplu işlem başına en fazla 1000 belge veya toplu iş başına yaklaşık 16 MB) önerilir ve dizin oluşturma performansını önemli ölçüde artırır.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Desteklenen Azure veri kaynakları için dizin oluşturucular , belge ekleme ve güncelleştirme için daha basit bir alternatif sunar. Daha fazla bilgi için bkz. Dizin oluşturucu işlemleri.
URI Parametreleri
| Parametre | Açıklama |
|---|---|
| hizmet adı | Gereklidir. Bunu arama hizmetinizin benzersiz, kullanıcı tanımlı adı olarak ayarlayın. |
| dizin adı | Belgelerin hangi dizinin gönderileceğini belirterek URI'de gereklidir. Aynı anda yalnızca bir dizine belge gönderebilirsiniz. |
| api-sürümü | Gereklidir. Geçerli kararlı sürüm: api-version=2020-06-30. Daha fazla sürüm için bkz. API sürümleri. |
İstek Üst Bilgileri
Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.
| Alanlar | Description |
|---|---|
| İçerik Türü | Gereklidir. Bunu olarak ayarlayın application/json |
| api-key | İsteğe bağlı olarak Azure rollerini kullanıyorsanız ve istekte taşıyıcı belirteci sağlanıyorsa bir anahtar gereklidir. Api anahtarı, arama hizmetinizde isteğin kimliğini doğrulayan benzersiz, sistem tarafından oluşturulan bir dizedir. Belgeleri karşıya yüklemek için yönetici API anahtarı gerekir. Ayrıntılar için bkz. Anahtar kimlik doğrulamasını kullanarak Azure AI Search'e bağlanma . |
İstek Gövdesi
İsteğin gövdesi dizine eklenecek bir veya daha fazla belge içeriyor. Belgeler, büyük/küçük harfe duyarlı benzersiz bir anahtarla tanımlanır. Her belge bir eylemle ilişkilendirilir: "upload", "delete", "merge" veya "mergeOrUpload". Karşıya yükleme istekleri, belge verilerini bir dizi anahtar/değer çifti olarak içermelidir.
{
"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)
...
},
...
]
}
| Özellik | Açıklama |
|---|---|
| @search.action | Gereklidir. Geçerli değerler "upload", "delete", "merge" veya "mergeOrUpload" değerleridir. Varsayılan olarak "karşıya yükleme" kullanılır. Eylemleri belge başına bir kez aynı toplu işlemde birleştirebilirsiniz. "karşıya yükleme": Karşıya yükleme eylemi, belge yeniyse eklendiği ve varsa güncelleştirildiği/değiştirileceği bir 'upsert' eylemine benzer. Güncelleştirme durumunda tüm alanlar değiştirilir. "delete": Delete belirtilen belgeyi dizinden kaldırır. Silme işleminde anahtar alanı dışında belirttiğiniz tüm alanlar yoksayılır. Belgeden tek bir alanı kaldırmak istiyorsanız, bunun yerine kullanın merge ve alanı açıkça olarak nullolarak ayarlayın. "mergeOrUpload": Bu eylem, belirtilen anahtara sahip bir belge dizinde zaten varsa birleştirme gibi davranır. Belge yoksa, yeni bir belgeyle karşıya yükleme gibi davranır. "merge": Birleştir, mevcut bir belgeyi belirtilen alanlarla güncelleştirir. Belge yoksa birleştirme başarısız olur. Birleştirmede belirttiğiniz herhangi bir alan belgede var olan alanın yerini alır. Bu, ilkel ve karmaşık tür koleksiyonları için de geçerlidir. İlkel koleksiyonlarda, belge ["budget"] değerine sahip Collection(Edm.String) türünde bir Etiketler alanı içeriyorsa ve Etiket için ["economy", "pool"] değeriyle bir birleştirme yürütürseniz, Etiketler alanının son değeri ["ekonomi", "havuz"] olur. ["bütçe", "ekonomi", "havuz"] olmayacaktır. Karmaşık koleksiyonlarda, belge [{ "Tür": "Bütçe Odası" değerine sahip Rooms adlı karmaşık bir koleksiyon alanı içeriyorsa, "BaseRate": 75.0 }], ve [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], Rooms alanının son değeri [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] değeriyle bir birleştirme yürütürseniz. Aşağıdakilerden biri olmayacak: [{ "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 }] (öğeleri sırayla birleştirin, sonra ekleri ekleyin) |
| key_field_name | Gereklidir. Dizinde belge anahtarı görevi görecek ve yalnızca benzersiz değerler içeren bir alan tanımı. Belge anahtarları yalnızca harf, sayı, kısa çizgi ("-"), alt çizgi ()"_" ve eşittir işareti ("=") içerebilir ve büyük/küçük harfe duyarlıdır. Daha fazla bilgi için bkz . Adlandırma kuralları. |
| field_name | Gereklidir. Ad-değer çiftleri; burada alanın adı dizin tanımındaki bir alan adına karşılık gelir. Değer kullanıcı tanımlıdır, ancak alan türü için geçerli olmalıdır. |
Not
İstek gövdesindeki eylemin ilk olarak yürütülmesi için herhangi bir sıralama garantisi yoktur. Tek bir istek gövdesinde aynı belgeyle ilişkilendirilmiş birden çok "birleştirme" eyleminin olması önerilmez. Aynı belge için birden çok "birleştirme" eylemi gerekiyorsa, belgeyi arama dizininde güncelleştirmeden önce birleştirme istemci tarafını gerçekleştirin.
Yanıt
Durum kodu: Başarılı bir yanıt için 200 döndürülür, yani tüm öğeler durabilir bir şekilde depolanmıştır ve dizine alınacaktır. Dizin oluşturma arka planda çalışır ve dizin oluşturma işlemi tamamlandıktan birkaç saniye sonra yeni belgeleri kullanıma sunar (sorgulanabilir ve aranabilir). Belirli bir gecikme, hizmet üzerindeki yüke bağlıdır.
Başarılı dizin oluşturma, tüm öğeler için durum özelliğinin true olarak ayarlanmasının yanı sıra statusCode özelliğinin 201 (yeni yüklenen belgeler için) veya 200 (birleştirilmiş veya silinmiş belgeler için) olarak ayarlanmasıyla gösterilir:
{
"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
}
]
}
Durum kodu: En az bir öğe başarıyla dizine alınamayınca 207 döndürülür. Dizine kaydedilmemiş öğelerde durum alanı false olarak ayarlanmıştır. errorMessage ve statusCode özellikleri, dizin oluşturma hatasının nedenini gösterir:
{
"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
}
]
}
errorMessage özelliği, mümkünse dizin oluşturma hatasının nedenini gösterir.
Aşağıdaki tabloda, yanıtta döndürülebilecek çeşitli belge başına durum kodları açıklanmaktadır. Bazı durum kodları isteğin kendisiyle ilgili sorunları, diğerleri ise geçici hata koşullarını gösterir. İkincisi, bir gecikmeden sonra yeniden denemeniz gerekir.
| Durum kodu | Anlamı | Yeniden denenebilir | Notlar |
|---|---|---|---|
| 200 | Belge başarıyla değiştirildi veya silindi. | yok | Silme işlemleri eşgüçlüdür. Başka bir ifadeyle, dizinde bir belge anahtarı olmasa bile, bu anahtarla silme işlemi denenmesi 200 durum koduyla sonuçlanır. |
| 201 | Belge başarıyla oluşturuldu. | yok | |
| 400 | Belgede dizinlenmesini engelleyen bir hata oluştu. | No | Yanıttaki hata iletisi, belgede neyin yanlış olduğunu gösterir. |
| 404 | Belirtilen anahtar dizinde olmadığından belge birleştirilemedi. | No | Bu hata, yeni belgeler oluşturduklarından karşıya yüklemelerde oluşmaz ve silme işlemleri için gerçekleşmez çünkü bunlar bir kez etkili olur. |
| 409 | Belgeyi dizine almaya çalışırken sürüm çakışması algılandı. | Yes | Aynı belgeyi eş zamanlı olarak birden çok kez dizine almaya çalıştığınızda bu durum oluşabilir. |
| 422 | Dizin geçici olarak kullanılamıyor çünkü 'allowIndexDowntime' bayrağı 'true' değerine ayarlanmış olarak güncelleştirildi. | Yes | |
| 503 | Arama hizmetiniz büyük olasılıkla ağır yük nedeniyle geçici olarak kullanılamıyor. | Yes | Kodunuzun yeniden denemeden önce beklemesi gerekir, yoksa hizmetin kullanım dışı durumunun uzaması riskiyle karşılaşırsınız. |
Not
İstemci kodunuz sık sık 207 yanıtıyla karşılaşıyorsa, olası nedenlerden biri sistemin yük altında olmasıdır. 503 için özelliğini denetleyerek statusCode bunu onaylayabilirsiniz. Bu durumda dizin oluşturma isteklerini azaltmanızı öneririz. Aksi takdirde, trafiğin dizini açılmazsa sistem 503 hatayla tüm istekleri reddetmeye başlayabilir.
Durum kodu: 429, dizin başına belge sayısı kotanızı aştığınızı gösterir. Daha yüksek kapasite sınırları için yeni bir dizin oluşturmanız veya yükseltmeniz gerekir.
Örnekler
Örnek: Tam tanımlı iki belgeyi karşıya yükleme
{
"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"
}
]
}
Not
Saat dilimi bilgilerini içeren değerleri dizininize yüklediğinizde DateTimeOffset Azure AI Search bu değerleri UTC olarak normalleştirir. Örneğin, 2019-01-13T14:03:00-08:00, 2019-01-13T22:03:00Z olarak depolanır. Saat dilimi bilgilerini depolamanız gerekiyorsa dizininize fazladan bir sütun eklemeniz gerekir.