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/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite

詳情請參閱Authentication Overview。
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

授權範圍

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

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

詳情請參閱Authentication Overview。

IAM 權限

需要 name 資源的下列 IAM 權限：

  • discoveryengine.operations.get

詳情請參閱 IAM 說明文件。
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

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

授權範圍

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

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

詳情請參閱Authentication Overview。

IAM 權限

需要 name 資源的下列 IAM 權限：

  • discoveryengine.operations.list

詳情請參閱 IAM 說明文件。

CancelOperationRequest

Operations.CancelOperation 的要求訊息。

欄位
name

string

要取消的作業資源名稱。

GetOperationRequest

Operations.GetOperation 的要求訊息。

欄位
name

string

作業資源名稱。

ListOperationsRequest

Operations.ListOperations 的要求訊息。

欄位
name

string

作業的父項資源名稱。
filter

string

標準清單篩選器。
page_size

int32

標準清單頁面大小。
page_token

string

標準清單頁面符記。
return_partial_success

bool

設為 true 時，可連線的作業會照常傳回，無法連線的作業則會傳回至 [ListOperationsResponse.unreachable] 欄位。

只有在跨集合讀取時 (例如 parent 設為 "projects/example/locations/-" 時)，才能使用 true。

根據預設，系統不支援這個欄位，如果設定這個欄位，會導致 UNIMPLEMENTED 錯誤，除非服務或產品專屬說明文件中明確記載其他情況。

ListOperationsResponse

Operations.ListOperations 的回應訊息。

欄位
operations[]

Operation

符合要求中指定篩選器的作業清單。
next_page_token

string

標準清單下一頁符記。
unreachable[]

string

未排序的清單。無法連線的資源。當要求設定 ListOperationsRequest.return_partial_success 並跨集合讀取時 (例如嘗試列出所有支援位置的所有資源)，系統會填入這個欄位。

作業

這個資源表示屬於網路 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。