取得 Azure AI 搜尋服務 REST API (索引子狀態)

發行項
11/13/2023

取得索引子狀態 作業可擷取索引子目前的狀態與執行記錄：

GET https://[service name].search.windows.net/indexers/[indexer name]/status?api-version=[api-version]&failIfCannotDecrypt=[true|false]
  Content-Type: application/json  
  api-key: [admin key]

URI 參數

參數	Description
服務名稱	必要。將此設定為搜尋服務的唯一使用者定義名稱。
索引子名稱	必要。要求 URI 會指定應該傳回狀態的索引子名稱。
api-version	必要。目前的穩定版本為 `api-version=2020-06-30` 。如需更多版本，請參閱 API 版本。
failIfCannotDecrypt	選擇性，如果未指定，則預設為 true。如果使用加密金鑰建立索引子，且搜尋服務無法存取加密金鑰，則擷取索引子狀態會失敗。如果為 false，則傳回的索引子狀態已將加密的屬性取代為 `"<encrypted>"` 預留位置。

要求標頭

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

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，而且要求會提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。取得物件定義的要求必須包含設定為系統管理員金鑰的 api 金鑰欄位， (而不是查詢金鑰) 。如需詳細資訊，請參閱使用金鑰驗證連線到 Azure AI 搜尋服務。

要求本文

無。

回應

狀態碼：回應成功時會傳回「200 確定」。回應本文包含有關整體索引子健康狀態、最後一個索引子調用的資訊，以及如果存在) ，則 (最近索引子調用的歷程記錄。

範例回應本文應如下所示：

{
    "status" : "running",
    "lastResult" : {
        "status" : "success",
        "errorMessage" : null,
        "startTime" : "2014-11-26T03:37:18.853Z",
        "endTime" : "2014-11-26T03:37:19.012Z",
        "errors" : [],
        "warnings" : [],
        "itemsProcessed" : 11,
        "itemsFailed" : 0,
        "initialTrackingState" : null,
        "finalTrackingState" : null
    },
    "executionHistory" : [
        {
            "status" : "success",
            "errorMessage" : null,
            "startTime" : "2014-11-26T03:37:18.853Z",
            "endTime" : "2014-11-26T03:37:19.012Z",
            "errors" : [],
            "warnings" : [],
            "itemsProcessed" : 11,
            "itemsFailed" : 0,
            "initialTrackingState" : null,
            "finalTrackingState" : null
        },
        {
            "status" : "transientFailure",
            "errorMessage" : null,
            "startTime" : "2014-11-26T03:28:10.125Z",
            "endTime" : "2014-11-26T03:28:12.007Z",
            "errors" : [
                {
                    "key" : "",
                    "name" : "The operation name describing where the error occurred. For example, 'Enrichment.LanguageDetectionSkill.SkillName'",
                    "errorMessage" : "Document key cannot be missing or empty.",
                    "statusCode" : 400,
                    "details" : "Any additional details, such as the WebApi response if executing a custom skill failed.",
                    "documentationLink" : "A link to relevant documentation. For example, 'https://go.microsoft.com/fwlink/?linkid=2099692'""
                }
            ],
            "warnings" : [
                {
                    "key" : "document id",
                    "name" : "The operation name describing where the warning occurred. For example, 'Enrichment.LanguageDetectionSkill.SkillName'",
                    "message" : "A warning doesn't stop indexing, and is intended to inform you of certain interesting situations, like when a blob indexer truncates the amount of text extracted from a blob."
                    "details" : "Any additional details, such as the WebApi response if executing a custom skill failed.",
                    "documentationLink" : "A link to relevant documentation. For example, 'https://go.microsoft.com/fwlink/?linkid=2099692'"
                }
            ],
            "itemsProcessed" : 1,
            "itemsFailed" : 1,
            "initialTrackingState" : null,
            "finalTrackingState" : null
        }
    ]
}

注意

如果使用加密金鑰建立索引子，則只有在搜尋服務可以存取加密金鑰時，才能擷取狀態的加密屬性。如果搜尋服務沒有加密金鑰的存取權，預設會傳回 400 不正確的要求。指定 failIfCannotDecrypt=false 以預留位置取代加密屬性來擷取狀態 "<encrypted>" 。

索引子狀態

索引子狀態可為下列值之一：

running 表示索引子正常執行。某些索引子執行可能仍然失敗，因此最好也檢查 lastResult 屬性。
error 表示索引子發生錯誤，而不需要人為介入即可更正。例如，資料來源認證可能已過期，或資料來源/目標索引的結構描述已受到中斷式的變更。

索引子執行結果

索引子執行結果包含單一索引子執行的相關資訊。最新的結果會顯示為索引子狀態的 lastResult 屬性。如果有其他最近的結果，則會傳回為索引子狀態的 executionHistory 屬性。

索引子執行結果包含下列屬性：

status：執行的狀態。如需詳細資訊，請參閱下方的索引子執行狀態。
errorMessage：失敗執行的錯誤訊息。
startTime：此執行啟動時的 UTC 時間。
endTime：此執行結束時的 UTC 時間。如果執行仍在進行中，則不會設定此值。
errors：如果有的話，專案層級錯誤的清單。如需範例，請參閱上述範例回應。從 API 版本 2020-06-30 開始，清單中每個錯誤將不再包含， "status" 因為針對專案層級錯誤，它一律為 false。從 API 版本 2020-06-30 開始，清單中的每個錯誤都包含新的屬性 "name" 、 "details" 和 "documentationLink" 。
警告：如果有的話，專案層級警告的清單。如需範例，請參閱上述範例回應。從 API 版本 2020-06-30 開始，清單中的每個警告都包含新的屬性 "name" 、 "details" 和 "documentationLink" 。
itemsProcessed： (的資料來源專案數目，例如，資料表資料列) 索引子在此執行期間嘗試編制索引。
itemsFailed：此執行期間失敗的專案數目。錯誤提供失敗的項目識別碼。
initialTrackingState：針對第一個索引子執行一律 為 null ，或者，如果未在使用的資料來源上啟用資料變更追蹤原則，則為 Null。如果啟用該原則，則在後續執行中，這個值就表示此執行處理的第一個 (最低) 變更追蹤值。
finalTrackingState：如果未在使用的資料來源上啟用資料變更追蹤原則，則一律為 Null 。否則，表示此執行成功處理的最新 (最高) 變更追蹤值。

索引子執行狀態

索引子執行狀態可擷取單一索引子執行的狀態。它具有下列值：

success 表示索引子執行已順利完成。
inProgress 表示索引子執行正在進行中。
transientFailure 表示索引子執行失敗。如需詳細資訊 ，請參閱 errorMessage 屬性。或許需要人為介入才能修正失敗。例如，修正資料來源與目標索引之間的架構不相容需要使用者動作，而暫時的資料來源停機時間則不需要。如果已定義索引子叫用，則會依排程繼續。如果排程上的索引子重複達到暫時性Failure 狀態而不進行進度，則索引子會開始執行頻率較不常的間隔， (最多至少每隔 24 小時執行一次) ，直到成功再次進行進度為止。
persistentFailure 表示索引子失敗的方式需要人為介入。排程的索引子執行會停止。解決此問題之後，請使用重設索引子 (Azure AI 搜尋 REST API) 重新開機排程的執行。
reset 表示索引子已透過呼叫重設索引子來重設索引子， (Azure AI 搜尋服務 REST API) 。

共用方式為