(預覽 REST API) 新增、更新或刪除檔
適用于：2023-07-01-Preview
重要
2023-07-01-Preview 新增：
- 支援檔中的向量欄位。
您可以使用 HTTP POST 將包含向量欄位的檔推送至指定的索引。 針對大型更新，批次處理 (每個批次最多 1000 份檔，或每個批次大約 16 MB) 可改善編制索引效能。
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2023-07-01-Preview
Content-Type: application/json
api-key: [admin key]
URI 參數
| 參數 | Description |
|---|---|
| 服務名稱 | 必要。 將此值設定為搜尋服務的唯一使用者定義名稱。 |
| 索引名稱 | 必要。 將此值設定為接收檔的索引名稱。 您一次只能將文件張貼到一個索引。 |
| api-version | 必要。 目前的預覽版本為 2023-07-23-Preview 。 如需更多版本，請參閱 API 版本 。 |
要求標頭
下表說明必要及選用的要求標頭。
| 欄位 | Description |
|---|---|
| Content-Type | 必要。 將此值設定為 application/json |
| api-key | 如果您使用 Azure 角色 ，並在要求上提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。 上傳檔需要系統管理員 API 金鑰。 如需詳細資訊，請參閱 使用金鑰驗證連線到 Azure AI 搜尋 服務。 |
要求本文
要求的本文包含一或多份要編製索引的文件。 檔是透過區分大小寫的金鑰唯一識別。 每個檔都與動作相關聯：「upload」、「delete」、「merge」 或 「mergeOrUpload」。 上傳要求必須包含文件資料做為一組索引鍵/值組。
向量欄位的類型為 Collection(Edm.Single) 。 向量資料是由單精確度浮點數陣列所組成。
根據原始內容的複雜度、長度或類型而定，向量欄位可以包含數千個內嵌。 Azure AI 搜尋服務不會將內容轉換成內嵌。 您推送至索引的檔必須包含您先前產生的內嵌。
{
"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),
"vector_field_name": [ array of single-precision floating point numbers ]
...
},
...
]
}
| 屬性 | 描述 |
|---|---|
| @search.action | 必要。 有效值為 「upload」、「delete」、「merge」 或 「mergeOrUpload」。 預設為 「upload」。 |
| key_field_name | 必要。 索引中做為檔索引鍵且只包含唯一值的欄位定義。 檔索引鍵只能包含字母、數位、連字號 ("-") 、底線 ("_") ，以及等號 ("=") 和區分大小寫。 |
| field_name | 必要。 名稱/值組，其中功能變數名稱對應至索引定義中的功能變數名稱。 此值是使用者定義的，但必須對欄位類型有效。 |
回應
狀態碼：成功回應會傳回 200，這表示所有專案都已永久儲存，且索引編制已開始。 索引會在背景執行，並讓新的檔可供 (，也就是索引作業完成之後，可查詢和可搜尋) 數秒。
當所有專案的狀態屬性設定為 true 時，就會指出成功編制索引。 新上傳檔的 statusCode 屬性應該是 201 () ，或合併或刪除的檔) 為 200 (。
範例
範例：上傳含有文字和向量內容的兩份檔
為了方便閱讀，下列範例顯示檔和內嵌的子集。 上傳檔要求的本文包含 108 份檔，每個檔都有一組完整的 「titleVector」 和 「contentVector」 內嵌。
POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
"value": [
{
"id": "1",
"title": "Azure App Service",
"content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
"category": "Web",
"titleVector": [
-0.02250031754374504,
. . .
],
"contentVector": [
-0.024740582332015038,
. . .
],
"@search.action": "upload"
},
{
"id": "2",
"title": "Azure Functions",
"content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
"category": "Compute",
"titleVector": [
-0.020159931853413582,
. . .
],
"contentVector": [
-0.02780858241021633,,
. . .
],
"@search.action": "upload"
}
. . .
]
}
注意
當您將具有時區資訊的值上傳 DateTimeOffset 至索引時，Azure AI 搜尋會將這些值正規化為 UTC。 例如，2019-01-13T14：03：00-08：00 會儲存為 2019-01-13T22：03：00Z。 如果您需要儲存時區資訊，請將額外的資料行新增至索引。