REST Resource: projects.locations.jobs

資源：Job

儲存空間批次作業工作說明。

JSON 表示法 
{
  "name": string,
  "description": string,
  "loggingConfig": {
    object (LoggingConfig)
  },
  "createTime": string,
  "scheduleTime": string,
  "completeTime": string,
  "counters": {
    object (Counters)
  },
  "errorSummaries": [
    {
      object (ErrorSummary)
    }
  ],
  "state": enum (State),

  // Union field source can be only one of the following:
  "bucketList": {
    object (BucketList)
  }
  // End of list of possible types for union field source.

  // Union field transformation can be only one of the following:
  "putObjectHold": {
    object (PutObjectHold)
  },
  "deleteObject": {
    object (DeleteObject)
  },
  "putMetadata": {
    object (PutMetadata)
  },
  "rewriteObject": {
    object (RewriteObject)
  }
  // End of list of possible types for union field transformation.
}
欄位
name

string

ID。工作的資源名稱。

格式：projects/{project}/locations/global/jobs/{jobId}。

例如 projects/123456/locations/global/jobs/job01。

jobId 在特定專案的特定位置中不得重複。如未指定 jobId，系統會指派伺服器產生的 ID。
description

string

(選用步驟) 使用者提供的職缺說明。

長度上限：以 Unicode 編碼時為 1024 個位元組。
loggingConfig

object (LoggingConfig)

(選用步驟) 記錄設定。
createTime

string (Timestamp format)

僅供輸出。工作建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
scheduleTime

string (Timestamp format)

僅供輸出。工作排定的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
completeTime

string (Timestamp format)

僅供輸出。工作完成的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
counters

object (Counters)

僅供輸出。工作進度資訊。
errorSummaries[]

object (ErrorSummary)

僅供輸出。並提供錯誤記錄檔項目的範例，方便您瞭解錯誤。
state

enum (State)

僅供輸出。工作狀態。
聯集欄位 source。指定要轉換的物件。source 只能是下列其中一個設定：
bucketList

object (BucketList)

指定要轉換的值區及其物件清單。
聯集欄位 transformation。要對物件執行的作業。transformation 只能是下列其中一個設定：
putObjectHold

object (PutObjectHold)

變更物件的訴訟保留狀態。
deleteObject

object (DeleteObject)

刪除物件。
putMetadata

object (PutMetadata)

更新物件中繼資料。可更新固定鍵和自訂中繼資料，以及固定鍵中繼資料。例如 Cache-Control、Content-Disposition、Content-Encoding、Content-Language、Content-Type、Custom-Time 和 object retention。
rewriteObject

object (RewriteObject)

重新寫入物件並更新中繼資料，例如 KMS 金鑰。

BucketList

說明要轉換的 bucket 及其物件清單。

JSON 表示法 
{
  "buckets": [
    {
      object (Bucket)
    }
  ]
}
欄位
buckets[]

object (Bucket)

這是必要旗標，要轉換的 bucket 及其物件清單。每個工作只能指定一個值區。如果指定多個值區，就會發生錯誤。

值區

說明要轉換的單一 bucket 及其物件的設定。

JSON 表示法 
{
  "bucket": string,

  // Union field object_configuration can be only one of the following:
  "prefixList": {
    object (PrefixList)
  },
  "manifest": {
    object (Manifest)
  }
  // End of list of possible types for union field object_configuration.
}
欄位
bucket

string

這是必要旗標，要轉換物件的值區名稱。
聯集欄位 object_configuration。指定要轉換的物件。object_configuration 只能是下列其中一個設定：
prefixList

object (PrefixList)

指定符合前置字串集的物件。
manifest

object (Manifest)

在資訊清單檔案中指定物件。

PrefixList

說明要轉換的物件前置字串。

JSON 表示法 
{
  "includedObjectPrefixes": [
    string
  ]
}
欄位
includedObjectPrefixes[]

string

(選用步驟) 指定一或多個物件前置字元。例如：

  • 如要比對單一物件，請使用單一前置字串 prefix1。

  • 如要比對多個物件，請使用以半形逗號分隔的前置字串 prefix1,prefix2。

  • 如要比對所有物件，請使用空白前置字串 ''

資訊清單

說明要轉換的物件清單。

JSON 表示法 
{
  "manifestLocation": string
}
欄位
manifestLocation

string

這是必要旗標，指定資訊清單檔案位置，例如 gs://bucket_name/path/object_name.csv。資訊清單是上傳至 Cloud Storage 的 CSV 檔案，內含要處理的單一物件或物件清單。資訊清單中的每個資料列都必須包含物件的 bucket 和 name。您可以選擇指定物件的 generation。如未指定 generation，系統會使用物件的目前版本。

檔案必須包含標題列，格式如下：bucket,name,generation。generation 欄為選填欄位。例如，假設使用者要求系統 將文字從英文翻譯成法文

bucket,name,generation
bucket_1,object_1,generation_1
bucket_1,object_2,generation_2
bucket_1,object_3,generation_3

注意：資訊清單檔案只能指定提供給工作的 bucket 中的物件。系統會忽略參照其他 bucket 中物件的資料列。

PutObjectHold

說明更新物件保留狀態的選項。

JSON 表示法 
{
  "temporaryHold": enum (HoldStatus),
  "eventBasedHold": enum (HoldStatus)
}
欄位
temporaryHold

enum (HoldStatus)

這是必要旗標，更新物件暫時性保留狀態。設定物件暫時性保留後，物件就無法刪除或取代。
eventBasedHold

enum (HoldStatus)

這是必要旗標，更新物件的依據事件訴訟保留狀態。設定物件事件型訴訟保留後，物件就無法刪除或取代。為了配合保留期限，重設值區中物件的時間。

HoldStatus

說明保留狀態。

列舉
HOLD_STATUS_UNSPECIFIED 預設值。物件訴訟保留狀態未變更。
SET 暫停通話。
UNSET 取消保留。

DeleteObject

說明刪除物件的選項。

JSON 表示法 
{
  "permanentObjectDeletionEnabled": boolean
}
欄位
permanentObjectDeletionEnabled

boolean

這是必要旗標，如果物件所屬值區已啟用版本管理功能，則可控管刪除行為。如為 true，系統會永久刪除使用中和非現行的物件。否則，版本化值區中的使用中物件會變為非現行，而原本就是非現行的物件則會略過。這項設定不會對軟刪除功能造成任何影響。如果啟用虛刪除功能，這項服務刪除的所有物件都會在虛刪除保留時長內保留，並可還原。如果啟用這項功能，且資訊清單未指定物件的產生方式，系統會發出 GetObjectMetadata 呼叫，判斷即時物件的產生方式。

PutMetadata

說明更新物件中繼資料的選項。

JSON 表示法 
{
  "customMetadata": {
    string: string,
    ...
  },
  "contentDisposition": string,
  "contentEncoding": string,
  "contentLanguage": string,
  "contentType": string,
  "cacheControl": string,
  "customTime": string
  "objectRetention": {
    object (ObjectRetention)
  }
}
欄位
customMetadata

map (key: string, value: string)

(選用步驟) 更新物件的自訂中繼資料。這項作業會新增或設定個別自訂中繼資料鍵/值組合。如果指定鍵的值為空白，系統會清除該鍵的值。未包含在要求中的現有自訂中繼資料鍵會維持不變。詳情請參閱「自訂中繼資料」。

包含 "key": "value" 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
contentDisposition

string

(選用步驟) 更新物件的Content-Disposition固定中繼資料。系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。詳情請參閱「Content-Disposition」。
contentEncoding

string

(選用步驟) 更新物件的固定中繼資料。Content-Encoding系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。詳情請參閱「Content-Encoding」。
contentLanguage

string

(選用步驟) 更新物件的固定內容語言中繼資料。中繼資料值必須使用 ISO 639-1 語言代碼。中繼資料值的長度上限為 100 個字元。系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。詳情請參閱「Content-Language」。
contentType

string

(選用步驟) 更新物件的Content-Type固定中繼資料。系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。詳情請參閱「Content-Type」。
cacheControl

string

(選用步驟) 更新物件的固定中繼資料。Cache-Control系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。此外，Custom-Time 的值不得減少。詳情請參閱「Cache-Control」。
customTime

string

(選用步驟) 更新物件的固定自訂時間中繼資料。系統會忽略要求中未設定的值。如要清除中繼資料，請設定空白值。詳情請參閱「自訂時間」。
objectRetention

object (ObjectRetention)

(選用步驟) 更新物件的保留設定。系統會忽略未設定的值。如要清除物件的保留設定，retentionMode 必須處於 UNLOCKED 狀態，且 retainUntilTime 必須設為空字串。如果物件的保留模式為 LOCKED，就無法清除保留設定或縮短 retainUntilTime。詳情請參閱「retainUntilTime」。

ObjectRetention

說明物件保留設定。

JSON 表示法 
{
  "retainUntilTime": string,
  "retentionMode": enum (RetentionMode)
}
欄位
retainUntilTime

string

這是必要旗標，物件的保留期限，在此期間，物件不會遭到刪除或覆寫。時間必須以 RFC 3339 格式指定，例如 YYYY-MM-DD'T'HH:MM:SS.SS'Z'。如要清除物件的保留時間，retentionMode 必須為 UNLOCKED，且 retainUntilTime 必須設為空字串。
retentionMode

enum (RetentionMode)

這是必要旗標，保留模式。

RetentionMode

保留模式。

列舉
RETENTION_MODE_UNSPECIFIED 未指定保留模式。
LOCKED 如果保留模式為 LOCKED，則無法移除或縮短 retainUntilTime。
UNLOCKED 如果保留模式為 UNLOCKED，則可移除或修改 retainUntilTime。

RewriteObject

說明物件重寫的選項。

JSON 表示法 
{
  "kmsKey": string
}
欄位
kmsKey

string

這是必要旗標，用來加密物件的 Cloud KMS 金鑰資源名稱。Cloud KMS 金鑰必須與物件位於相同位置。詳情請參閱「使用 Cloud KMS 金鑰加密物件」一文。

格式：projects/{project}/locations/{locationid}/keyRings/{keyring}/cryptoKeys/{key}

例如：projects/123456/locations/us-central1/keyRings/my-keyring/cryptoKeys/my-key。系統會重新寫入物件，並設定指定的 KMS 金鑰。

LoggingConfig

指定 Cloud Logging 行為。

JSON 表示法 
{
  "logActions": [
    enum (LoggableAction)
  ],
  "logActionStates": [
    enum (LoggableActionState)
  ]
}
欄位
logActions[]

enum (LoggableAction)

這是必要旗標，指定要記錄的動作。
logActionStates[]

enum (LoggableActionState)

這是必要旗標，系統記錄動作的狀態。如果為空值，系統不會產生任何記錄。

LoggableAction

可記錄的動作類型。

列舉
LOGGABLE_ACTION_UNSPECIFIED 非法值，避免允許預設值。
TRANSFORM 這項工作中對應的轉換動作。

LoggableActionState

可記錄的動作狀態篩選器。

列舉
LOGGABLE_ACTION_STATE_UNSPECIFIED 非法值，避免允許預設值。
SUCCEEDED 已順利完成 LoggableAction。SUCCEEDED 動作會記錄為 [INFO][google.logging.type.LogSeverity.INFO]。
FAILED LoggableAction 終止，狀態為「發生錯誤」。FAILED 動作會記錄為 [ERROR][google.logging.type.LogSeverity.ERROR]。

計數器

說明工作的進度詳細資料。

JSON 表示法 
{
  "totalObjectCount": string,
  "succeededObjectCount": string,
  "failedObjectCount": string
}
欄位
totalObjectCount

string (int64 format)

僅供輸出。列出的物件數量。
succeededObjectCount

string (int64 format)

僅供輸出。已完成的物件數量。
failedObjectCount

string (int64 format)

僅供輸出。失敗的物件數量。

ErrorSummary

依錯誤代碼分類的錯誤摘要，以及錯誤記錄項目計數和範例。

JSON 表示法 
{
  "errorCode": enum (Code),
  "errorCount": string,
  "errorLogEntries": [
    {
      object (ErrorLogEntry)
    }
  ]
}
欄位
errorCode

enum (Code)

這是必要旗標，標準錯誤代碼。
errorCount

string (int64 format)

這是必要旗標，每 errorCode 發生錯誤的次數。
errorLogEntries[]

object (ErrorLogEntry)

這是必要旗標，錯誤記錄範例。

程式碼

定義用於處理 gRPC API 回應的錯誤代碼。

如果適用多個錯誤代碼，請傳回最明確的錯誤代碼。例如，如果 OUT_OF_RANGE 與 FAILED_PRECONDITION 代碼都適用，則最好使用前者。同樣地，NOT_FOUND 或 ALREADY_EXISTS 的使用順序應高於 FAILED_PRECONDITION。

列舉
OK

作業順利完成時傳回。

HTTP 對應：200 OK
CANCELLED

作業已取消，一般由呼叫者取消。

HTTP 對應：499 用戶端已關閉要求
UNKNOWN

發生不明錯誤，舉例來說，當從其他位址空間收到的 Status 值屬於這個位址空間中不明的錯誤空間時，就可能傳回此錯誤；由 API 發出但未傳回足夠錯誤資訊的錯誤也可能轉換為此錯誤。

HTTP 對應：500 內部伺服器錯誤
INVALID_ARGUMENT

用戶端指定了無效的引數。請注意，這與 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 表示引數有問題，無論系統狀態為何皆適用 (例如檔案名稱格式錯誤)。

HTTP 對應：400 錯誤的要求
DEADLINE_EXCEEDED

期限於作業完成之前過期。針對變更系統狀態的作業，即使作業已成功完成，也可能傳回此錯誤。例如，來自伺服器的成功回應延遲時間可能已長到足以使期限過期。

HTTP 對應：504 閘道逾時
NOT_FOUND

找不到某些要求的實體 (例如檔案或目錄)。

伺服器開發人員注意事項：如果系統拒絕整類使用者 (例如逐步推出功能或未記錄的允許清單) 的要求，可以使用 NOT_FOUND。如果拒絕部分使用者 (例如使用者型存取控制) 的要求，則必須使用 PERMISSION_DENIED。

HTTP 對應：404 找不到
ALREADY_EXISTS

用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。

HTTP 對應：409 衝突
PERMISSION_DENIED

呼叫者沒有執行指定作業的權限。不得針對因耗用某些資源所導致的拒絕情形使用 PERMISSION_DENIED (請針對這些錯誤改用 RESOURCE_EXHAUSTED)。如果無法識別呼叫者，不得使用 PERMISSION_DENIED (請針對這些錯誤改用 UNAUTHENTICATED)。此錯誤代碼並不表示要求有效，或存在要求的實體，或滿足其他先決條件。

HTTP 對應：403 禁止
UNAUTHENTICATED

要求沒有作業的有效驗證憑證。

HTTP 對應：401 未授權
RESOURCE_EXHAUSTED

已耗盡某些資源，或許是每位使用者的配額，或許是完整檔案系統空間不足。

HTTP 對應：429 太多要求
FAILED_PRECONDITION

作業已遭拒絕，因為系統不在執行作業所需的狀態下。例如，要刪除的目錄還有內容、rmdir 作業套用至非目錄等。

服務實作人員可以參考下列指南，決定要使用 FAILED_PRECONDITION、ABORTED 或 UNAVAILABLE：

  • 如果用戶端只能重試失敗的呼叫，請使用 UNAVAILABLE。
  • 如果用戶端應在較高層級重試，請使用 ABORTED。舉例來說，當用戶端指定的「test-and-set」失敗時，表示用戶端應重新開始「read-modify-write」序列。
  • 如果用戶端不應在系統狀態明確修正完畢之前重試，請使用 FAILED_PRECONDITION。舉例來說，如果「rmdir」因目錄不是空白而失敗，則應傳回 FAILED_PRECONDITION，因為用戶端必須等到目錄中的檔案都刪除之後才重試。

HTTP 對應：400 錯誤的要求
ABORTED

作業已取消，通常是因為例如順序器檢查失敗或交易已取消等並行問題所導致。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE，請參閱以上指南。

HTTP 對應：409 衝突
OUT_OF_RANGE

嘗試作業時超過有效範圍，例如，搜尋或讀取檔案結尾之後的內容。

與 INVALID_ARGUMENT 不同，此錯誤表示如果系統狀態變更則可修正的問題。舉例來說，如果要求在 [0, 2^32-1] 範圍以外的位移讀取資料，32 位元檔案系統會產生 INVALID_ARGUMENT，但如果要求從超過目前檔案大小的位移讀取資料，則會產生 OUT_OF_RANGE。

FAILED_PRECONDITION 與 OUT_OF_RANGE 之間有不少重疊的地方。我們建議您在適用時使用 OUT_OF_RANGE (較為特定的錯誤)，這樣在空間中進行迭代作業的呼叫者就可以在完成時輕鬆找到要偵測的 OUT_OF_RANGE 錯誤。

HTTP 對應：400 錯誤的要求
UNIMPLEMENTED

未實作作業或作業在此服務中不受支援/未啟用。

HTTP 對應：501 未實作
INTERNAL

內部錯誤。這表示基礎系統預期的某些不變的情形已被打破。此錯誤代碼保留供嚴重錯誤使用。

HTTP 對應：500 內部伺服器錯誤
UNAVAILABLE

服務目前無法使用。這很可能是暫時性問題，可透過重試輪詢來解決。請注意，重試非等冪作業並不一定安全。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE，請參閱以上指南。

HTTP 對應：503 服務不可用
DATA_LOSS

無法復原的資料遺失或損毀。

HTTP 對應：500 內部伺服器錯誤

ErrorLogEntry

描述發生錯誤的項目。

JSON 表示法 
{
  "objectUri": string,
  "errorDetails": [
    string
  ]
}
欄位
objectUri

string

這是必要旗標，僅供輸出。物件網址。例如 gs://my_bucket/object.txt。
errorDetails[]

string

(選用步驟) 僅供輸出。每項工作的每個錯誤代碼最多會記錄 5 個錯誤記錄項目。

狀態

說明工作狀態。

列舉
STATE_UNSPECIFIED 預設值。這個值不會使用。
RUNNING 執行中。
SUCCEEDED 已順利完成。
CANCELED 使用者已取消。
FAILED 因發生無法復原的錯誤而終止。

方法

cancel

 取消指定專案中指定位置的批次工作。

create

 在指定專案的指定位置建立批次工作。

delete

 刪除指定專案中指定位置的批次工作。

get

 在指定專案中，取得指定位置的批次工作。

list

 列出指定專案中指定位置的所有批次工作。