Package google.longrunning

索引

• Operations (介面)
• CancelOperationRequest (訊息)
• DeleteOperationRequest (訊息)
• GetOperationRequest (訊息)
• ListOperationsRequest (訊息)
• ListOperationsResponse (訊息)
• Operation (訊息)
• WaitOperationRequest (訊息)

作業

使用 API 服務管理長時間執行作業。

如果 API 方法通常需要長時間才能完成作業，則可能會向用戶端傳回 Operation。這樣一來，用戶端即可藉由輪詢作業資源，以非同步的方式透過這個介面接收真正的回應；或是傳遞作業資源至其他 API (例如 Google Cloud Pub/Sub API) 來接收回應。凡是傳回長時間執行作業的 API 服務都應實作 Operations 介面，讓開發人員能獲得一致的用戶端體驗。

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty) 開始非同步取消長時間執行的作業。伺服器會盡全力取消作業，但不保證一定會成功。如果伺服器不支援這個方法，就會傳回 google.rpc.Code.UNIMPLEMENTED。用戶端可以使用 Operations.GetOperation 或其他方法，查看作業是否已成功取消，或是作業即使在用戶端下令取消之後仍然執行完畢。作業在成功取消之後，並不會遭到刪除，而是會成為擁有 Operation.error 值，且 google.rpc.Status.code 為 1 (也就是 Code.CANCELLED) 的作業。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-vision 詳情請參閱驗證總覽。

DeleteOperation
rpc DeleteOperation(DeleteOperationRequest) returns (Empty) 刪除長時間執行的作業。此方法指示用戶端不再對作業結果感興趣。它不會取消作業。如果伺服器不支援這個方法，則會傳回 google.rpc.Code.UNIMPLEMENTED。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-vision 詳情請參閱驗證總覽。

GetOperation
rpc GetOperation(GetOperationRequest) returns (Operation) 取得長時間執行作業的最新狀態。用戶端可以使用這個方法按照 API 服務建議的間隔查詢作業結果。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-vision 詳情請參閱驗證總覽。

ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse) 列出符合要求中指定篩選器的作業。如果伺服器不支援這個方法，則會傳回 UNIMPLEMENTED。 附註：name 繫結允許 API 服務覆寫繫結以使用不同的資源名稱架構，例如 users/*/operations。如要覆寫繫結，API 服務可以新增繫結 (例如 "/v1/{name=users/*}/operations") 至其服務設定。為了顧及回溯相容性，預設名稱中包含作業集合 ID，但覆寫使用者必須確保名稱繫結是父項資源，且不含作業集合 ID。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-vision 詳情請參閱驗證總覽。

WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation) 等待指定的長時間執行作業完成，或是最多等到指定的逾時時間為止，並傳回最新狀態。如果作業已經完成，系統會立刻傳回最新狀態。如果指定的逾時時間比預設的 HTTP/RPC 逾時時間還要長，則會使用 HTTP/RPC 逾時時間。如果伺服器不支援這個方法，則會傳回 google.rpc.Code.UNIMPLEMENTED。請注意，這個方法會盡可能完成作業。由於它可能會在作業達到指定的逾時時間 (包含立即) 之前就傳回最新狀態，因此就算您立即收到回應，也不代表作業已經完成。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/cloud-vision 詳情請參閱驗證總覽。

CancelOperationRequest

Operations.CancelOperation 的要求訊息。

欄位
name	string 要取消的作業資源名稱。

DeleteOperationRequest

Operations.DeleteOperation 的要求訊息。

欄位
name	string 要刪除的作業資源名稱。

GetOperationRequest

Operations.GetOperation 的要求訊息。

欄位
name	string 作業資源名稱。

ListOperationsRequest

Operations.ListOperations 的要求訊息。

欄位
name	string 作業的父項資源名稱。
filter	string 標準清單篩選器。
page_size	int32 標準清單頁面大小。
page_token	string 標準清單頁面符記。

ListOperationsResponse

Operations.ListOperations 的回應訊息。

欄位
operations[]	Operation 符合要求中指定篩選器的作業清單。
next_page_token	string 標準清單下一頁憑證。

作業

這個資源表示屬於網路 API 呼叫結果的長時間執行作業。

欄位
name	string 伺服器指派的名稱，而且只有在當初傳回這個名稱的服務中是不重複項目。如果您使用預設的 HTTP 對應，則 name 應採用 operations/some/unique/name 格式。
metadata	Any 與作業相關聯的服務專屬中繼資料，通常包含進度資訊和常用中繼資料 (例如建立時間)。部分服務可能不會提供這類中繼資料。凡是會傳回長時間執行作業的方法，都應記錄中繼資料類型 (如果有的話)。
done	bool 如果值為 false，代表作業仍在執行中。如果值為 true，代表作業已執行完畢，系統會顯示 error 或 response 的執行結果。
聯集欄位 result。這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，系統會將結果設定為 error 或 response。result 只能是下列其中一個設定：
error	Status 作業執行失敗或遭到取消時，所顯示的錯誤結果。
response	Any 作業執行成功時的一般回應。如果原始方法在執行成功時沒有傳回資料 (例如 Delete)，則回應為 google.protobuf.Empty。如果原始方法是標準的 Get/Create/Update，回應則應該為資源。如果是其他方法，回應須包含類型 XxxResponse，其中 Xxx 是原始方法名稱。舉例來說，如果原始方法名稱為 TakeSnapshot()，則可推測回應類型為 TakeSnapshotResponse。

WaitOperationRequest

Operations.WaitOperation 的要求訊息。

欄位
name	string 要等待的作業資源名稱。
timeout	Duration 逾時前的等待時間上限。如果留空，系統最多會等待基本 HTTP/RPC 通訊協定允許的時間。如果同時指定了 RPC 內容期限，則系統會採用較短的期限。