新增、更新或移除檔案 （預覽 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 參數
| 參數 | 描述 |
|---|---|
| 服務名稱 | 必填。 將此值設定為搜尋服務的唯一用戶定義名稱。 |
| 索引名稱 | 必填。 將此值設定為接收檔的索引名稱。 您一次只能將文件張貼至一個索引。 |
| api-version | 如需更多版本，請參閱 API 版本。 |
要求標頭
下表描述必要和選擇性的要求標頭。
| 領域 | 描述 |
|---|---|
| Content-Type | 必填。 將此值設定為 application/json |
| api-key | 如果您使用 Azure 角色，而且要求會提供持有人令牌，則為選擇性，否則需要密鑰。 api-key 是唯一的系統產生字串，可驗證對搜尋服務的要求。 上傳檔需要系統管理員 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”。 預設為「上傳」。 |
| 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。 如果您需要儲存時區資訊，請將額外的數據行新增至您的索引。