Package google.longrunning

索引

作業套件

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

如果 API 方法通常需要較長的時間才能完成作業，則可能會向用戶端傳回 Operation。這樣一來，用戶端即可藉由輪詢作業資源，以非同步的方式透過這個介面接收實際回應；或是將作業資源傳送至其他 API (例如 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/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽。
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

刪除長時間執行的作業。此方法指示用戶端不再對作業結果感興趣。它不會取消作業。如果伺服器不支援這個方法，則會傳回 google.rpc.Code.UNIMPLEMENTED。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽。
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

取得長時間執行作業的最新狀態。用戶端可以使用這個方法按照 API 服務建議的間隔查詢作業結果。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽。
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

列出符合要求中指定篩選器的作業。如果伺服器不支援這個方法，則會傳回 UNIMPLEMENTED。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽。
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

等待指定的長時間執行作業完成，或最多達到指定的逾時時間，並傳回最新狀態。如果作業已經完成，系統會立刻傳回最新狀態。如果指定的逾時時間比預設的 HTTP/RPC 逾時時間還要長，則會使用 HTTP/RPC 逾時時間。如果伺服器不支援這個方法，則會傳回 google.rpc.Code.UNIMPLEMENTED。請注意，這個方法會盡可能完成作業。由於它可能會在作業達到指定的逾時時間 (包含立即) 之前就傳回最新狀態，因此就算您立即收到回應，也不代表作業已經完成。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽。

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/{unique_id} 結尾的資源名稱。
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 內容期限，則系統會採用較短的期限。