2016-12-18

Azure Search - Part 6 (使用 REST API 上傳資料至 Azure Search)

可以上傳資料到 Azure Search index 的方式有二個:

  1. 推送資料至 index(Push data to an index)

    • 使用 .NET SDKREST API
    • 可保持較高的資料一致性
    • 可個別或是批次上傳
  2. 拉資料進 index(Pull data into an index)

    • 會檢查支援的資料來源並主動上傳
    • 可以辨識新 document 、也可追蹤現有 document 的變更,減少主動管理 index 資料
    • 透過 indexers 支援 Blob 儲存體 (預覽)DocumentDBAzure SQL DatabaseAzure VM 上的 SQL Server

今天來試試 REST API 的用法,透過 REST API 上傳資料就是 將新增、修改或是刪除的 document 放在 request body,發出 HTTP POST request 到 index endpoint 的 URL .

準備 API Key

Azure Search Service Key

key Type 備註 用途說明
admin keys(系統管理金鑰) 主要/次要 管理服務、建立/刪除 Index、索引子、資料來源;主要/次要用途相同
query keys(查詢金鑰) - 提供 client 端用來讀取 index 與 document
  1. 登入 Azure Portal
  2. 開啟 Azure Search
  3. 點擊 金鑰

1.AZUREKEY

  1. 取得 主要管理金鑰 或是 次要管理金鑰
    • 兩者皆可用來建立 index

      1-4ADMINKEY

1. 決定要用哪一種 action 進行 index

資料 --> document(含有 key) + property(action:Upload,Merge,MergeOrUpload,Delete) == json object --> value(陣列) ==> value 放在 request body 中,HTTP POST 至 Azure Search Service 的 index endpoint 的 URL

  1. 資料輸出成 JSON object
  2. JSON object 由 documentproperty 組成
  3. 一個或多個 JSON object 組成 value
  4. value 放在 request body 透過 HTTP POST 至 index endpoint 的 URL
Action 說明 必要欄位 注意事項
Upload document 不存在就建立,存在就取代 key,及其他想指定的欄位 更新 document 時,未指定的欄位會設定為 null,即使之前已設定過
Merge 使用指定的欄位更新現有 document。 如果 document 不存在於 index 中,merge 就會失敗。 KEY,及想更新的欄位 merge 中指定的任何欄位將取代文件中現有的欄位,可用來移除個別欄位
MergeOrUpload 有指定 key 的 document 已存在 index 中,則 Merge,否則就 Upload key,及其他想指定的欄位 -
Delete 從 index 中移除指定的 document key 除了 key 之外都會被忽略

2. 建立 HTTP request 跟 request body

2-1. request 和 request header

  1. URL
  • Service name
  • Index name
  • API 版本

我在範例有看到 2016-09-01 版本,但正式文件跟 Azure Portal 都還沒有 2-1-1apiversion

```
https://[search service].search.windows.net/indexes/hotels/docs/index?api-version=2015-02-28
```
  1. header
    • Content-Type
    • api-key
Content-Type: application/json
api-key: [admin key]

2-2. request body

  • 使用 json
  • 包含 一個 value object
  • value 中有多個 document
  • document 需要有 action("@search.action") 及 key, 還有其他想指定的欄位
  • 每個 request 不得超過 1000 document 或是 16 MB (看哪個先滿足)
{
    "value": [
        {
            "@search.action": "upload",
            "hotelId": "1",
            "baseRate": 199.0,
            "description": "Best hotel in town",
            "description_fr": "Meilleur hôtel en ville",
            "hotelName": "Fancy Stay",
            "category": "Luxury",
            "tags": ["pool", "view", "wifi", "concierge"],
            "parkingIncluded": false,
            "smokingAllowed": false,
            "lastRenovationDate": "2010-06-27T00:00:00Z",
            "rating": 5,
            "location": { "type": "Point", "coordinates": [-122.131577, 47.678581] }
        },
        {
            "@search.action": "upload",
            "hotelId": "2",
            "baseRate": 79.99,
            "description": "Cheapest hotel in town",
            "description_fr": "Hôtel le moins cher en ville",
            "hotelName": "Roach Motel",
            "category": "Budget",
            "tags": ["motel", "budget"],
            "parkingIncluded": true,
            "smokingAllowed": true,
            "lastRenovationDate": "1982-04-28T00:00:00Z",
            "rating": 1,
            "location": { "type": "Point", "coordinates": [-122.131577, 49.678581] }
        },
        {
            "@search.action": "mergeOrUpload",
            "hotelId": "3",
            "baseRate": 129.99,
            "description": "Close to town hall and the river"
        },
        {
            "@search.action": "delete",
            "hotelId": "6"
        }
    ]
}

3. HTTP Response Code

Status Code 說明 Response Body
200 成功建立 { "value": [ { "key": "unique_key_of_document", "status": true, "errorMessage": null }, ... ]}
207 至少有一個項目未成功,通常表示 loading 即將到達上限,可建立暫停及重試機制 { "value": [ { "key": "unique_key_of_document", "status": false, "errorMessage": "The search service is too busy to process this document. Please try again later." }, ... ]}
429 index 的 document 數量已達上限 -
503 所有項目皆未成功,表示系統已過載 -

REST API 對於沒有 .NET SDK 的環境是另個方便的選擇,使用上也很容易.

參考資料

  1. 使用 REST API 將資料上傳至 Azure 搜尋服務

沒有留言:

張貼留言