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

(非必要) 使用者提供的工作說明。

長度上限：以萬國碼編碼時為 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。
rewriteObject

object (RewriteObject)

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

BucketList

說明要轉換的資料集和相關物件清單。

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

object (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

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

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
}
欄位
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

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

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 不同，此錯誤表示如果系統狀態變更則可修正的問題。舉例來說，如果 32 位元檔案系統要求讀取的偏移量不在 [0,2^32-1] 的範圍內，則會產生 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

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