(Azure AI 搜尋 REST API) 新增、更新或刪除檔

發行項
11/13/2023

您可以使用 HTTP POST 將搜尋檔匯入指定的索引。針對大型更新，建議每個批次最多批次處理 (1000 份檔，或建議每個批次大約 16 MB) ，並大幅改善編制索引效能。

POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]   
  Content-Type: application/json   
  api-key: [admin key]

針對支援的 Azure 資料來源，索引子提供更簡單的替代方式來新增和更新檔。如需詳細資訊，請參閱索引子作業。

URI 參數

參數	Description
服務名稱	必要。將此設定為搜尋服務的唯一使用者定義名稱。
索引名稱	URI 上的必要專案，指定要張貼檔的索引。您一次只能將文件張貼到一個索引。
api-version	必要。目前的穩定版本是 `api-version=2020-06-30` 。如需更多版本，請參閱 API 版本。

要求標頭

下表說明必要及選用的要求標頭。

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，並在要求上提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。上傳檔需要系統管理員 API 金鑰。如需詳細資訊，請參閱使用金鑰驗證連線到 Azure AI 搜尋服務。

要求本文

要求的本文包含一或多份要編製索引的文件。檔是由唯一區分大小寫的索引鍵所識別。每個檔都與動作相關聯：「upload」、「delete」、「merge」或「mergeOrUpload」。上傳要求必須包含文件資料做為一組索引鍵/值組。

{  
  "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)  
        ...  
    },  
    ...  
  ]  
}

屬性	描述
@search.action	必要。有效值為「upload」、「delete」、「merge」或「mergeOrUpload」。預設為「upload」。您可以在相同的批次中合併每個檔的一個動作。「upload」：上傳動作類似于 'upsert'，如果檔是新的，則會插入檔，如果檔存在，則會更新/取代。更新案例中會取代所有欄位。「delete」：Delete 會從索引中移除指定的檔。您在刪除作業中指定的任何欄位，除了索引鍵欄位之外，將會忽略。如果您想要從檔中移除個別欄位，請改用 `merge` ，並將欄位明確設定為 `null` 。「mergeOrUpload」：如果具有指定索引鍵的檔已存在於索引中，此動作的行為會像合併一樣。如果檔不存在，其行為就像使用新檔上傳一樣。「merge」：合併會以指定的欄位更新現有的檔。如果檔不存在，合併就會失敗。您在合併中指定的任何欄位將取代文件中現有的欄位。這也適用于基本型別和複雜類型的集合。在基本集合中，如果檔包含 Collection 類型的 Tags 欄位， (Edm.String) 值為 [「budget」]，而且您針對 Tag 執行與 [「經濟」，「pool」] 值的合併，則 Tags 欄位的最終值會是 [「經濟」，「pool」。此值將不會是 ["budget", "economy", "pool"]。在複雜的集合中，如果檔包含名為 Room 的複雜集合欄位，其值為 [{ 「Type」：「Budget Room」，「BaseRate」： 75.0 }]，而您執行合併的值為 [{ 「Type」：「Standard Room」 }， { 「Type」：「Budget Room」，「BaseRate」： 60.5 }]，[會議室] 欄位的最終值為 [{ 「Type」：「Standard Room」 }， { 「Type」：「Budget Room」，「BaseRate」： 60.5 }]。它不會是下列其中一項： [{ 「Type」：「Budget Room」，「BaseRate」： 75.0 }， { 「Type」：「Standard Room」 }， { 「Type」：「Budget Room」，「BaseRate」： 60.5 }] (附加元素) [{ 「Type」：「Standard Room」，「BaseRate」： 75.0 }， { 「Type」：「Budget Room」，「BaseRate」： 60.5 }] (合併元素，然後附加任何額外專案)
key_field_name	必要。索引中做為檔索引鍵且只包含唯一值的欄位定義。檔索引鍵只能包含字母、數位、連字號 (`"-"`) 、底線 (`"_"`) ，以及等號 (`"="`) 和區分大小寫。如需詳細資訊，請參閱命名規則。
field_name	必要。名稱/值組，其中功能變數名稱對應至索引定義中的功能變數名稱。此值是使用者定義的，但必須對欄位類型有效。

注意

要求主體中的動作不會先執行順序保證。不建議在單一要求本文中有多個與相同檔相關聯的「合併」動作。如果相同檔有多個「合併」動作，請在更新搜尋索引中的檔之前，先執行合併用戶端。

回應

狀態碼：會針對成功的回應傳回 200，這表示所有專案都已永久儲存，並開始編制索引。索引會在背景執行，並讓新的檔可供 (，也就是索引作業完成之後，可查詢和可搜尋) 數秒。特定延遲取決於服務的負載。

成功編制索引是由針對所有專案設定為 true 的狀態屬性，以及針對新上傳的檔設定為 201 (statusCode 屬性，或針對合併或刪除) 的檔設定為 200 () ：

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

狀態碼：當至少有一個專案未成功編制索引時，就會傳回 207。尚未編制索引的專案會將狀態欄位設定為 false。 errorMessage 和 statusCode 屬性會指出索引編制錯誤的原因：

{
  "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 屬性會指出可能的話，索引編制錯誤的原因。

下表說明可在回應中傳回的各種個別檔狀態碼。有些狀態碼表示要求本身的問題，而其他則表示暫時性錯誤狀況。對於後者，您應在延遲之後重試。

狀態碼	意義	可重試	備註
200	已成功修改或刪除文件。	n/a	刪除作業為等冪。也就是說，即使索引中沒有檔索引鍵，嘗試使用該索引鍵的刪除作業會導致 200 狀態碼。
201	已成功建立文件。	n/a
400	文件中發生錯誤，使得無法對它編製索引。	No	回應中的錯誤訊息指出檔發生錯誤。
404	無法合併檔，因為指定的索引鍵不存在於索引中。	No	因為上傳會建立新檔，所以不會發生此錯誤，而且不會發生刪除，因為它們是等冪的。
409	當您嘗試編製文件的索引時偵測到版本衝突。	Yes	當您嘗試並行對相同的文件編製索引時，也可能會發生此情況。
422	索引暫時無法使用，因為已藉由將 'allowIndexDowntime' 旗標設定為 'true' 來更新它。	Yes
503	您的搜尋服務暫時無法使用，可能是因為負載過重。	Yes	在此情況下，您的程式碼在重試之前應等待，否則可能會導致服務長時間無法使用。

注意

如果用戶端程式碼經常發生 207 回應，可能的原因之一是系統負載過重。您可以檢查 statusCode 屬性是否為 503 來確認這一點。如果是這種情況，建議您節流索引要求。否則，如果編製索引流量並未減緩，系統可能會開始拒絕所有要求並產生 503 錯誤。

「狀態碼：429」表示每個索引的文件數量上已經超過您的配額。您必須建立新的索引，或進行升級以取得更高的容量限制。

範例

範例：上傳兩個完整定義的檔

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

注意

當您將具有時區資訊的值上傳 DateTimeOffset 至索引時，Azure AI 搜尋會將這些值正規化為 UTC。例如，2019-01-13T14：03：00-08：00 會儲存為 2019-01-13T22：03：00Z。如果您需要儲存時區資訊，則必須在索引中新增額外的資料行。

(Azure AI 搜尋 REST API) 新增、更新或刪除檔

URI 參數

要求標頭

要求本文

回應

範例

另請參閱

其他資源