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

标识符。作业的资源名称。

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

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

jobId 在给定项目的给定位置中是唯一的。如果未指定 jobId，系统会分配服务器生成的标识符。
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。
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)

可选。更新对象的自定义元数据。此操作用于添加或设置各个自定义元数据键值对。系统会清除使用空值指定的键的值。请求中未包含的现有自定义元数据键将保持不变。如需了解详情，请参阅 Custom-Metadata。

包含一系列 "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 Client Closed Request
UNKNOWN

未知错误。例如，当从另一个地址空间接收到的 Status 值属于此地址空间中未知的错误空间时，可能返回此错误。另外，因 API 没有返回足够错误信息而引发的错误也可能会转换为此错误。

HTTP 映射：500 内部服务器错误
INVALID_ARGUMENT

客户端指定的参数无效。请注意，这与 FAILED_PRECONDITION 不同。无论系统状态如何，INVALID_ARGUMENT 都会指出有问题的参数（例如文件名格式错误）。

HTTP 映射：400 Bad Request
DEADLINE_EXCEEDED

在操作完成之前截止期限已过。对于更改系统状态的操作，即使操作已成功完成，也可能会返回此错误。例如，服务器的成功响应可能会延迟足够长的时间以使截止期限过期。

HTTP 映射：504 Gateway Timeout
NOT_FOUND

找不到所请求的部分实体（例如，文件或目录）。

服务器开发者注意：如果要拒绝整个一类用户的请求（例如，功能逐步发布的用户或未正式加入许可名单的用户），则可以使用 NOT_FOUND。如果要拒绝某一类用户中部分用户的请求（例如，基于用户的访问权限控制），则必须使用 PERMISSION_DENIED。

HTTP 映射：404 Not Found
ALREADY_EXISTS

客户端尝试创建的实体（例如文件或目录）已存在。

HTTP 映射：409 Conflict
PERMISSION_DENIED

调用者无权执行指定的操作。如果遭拒的原因是由于部分资源已用尽，则不得使用 PERMISSION_DENIED（请改用 RESOURCE_EXHAUSTED 来表示此类错误）。如果调用者无法识别，则不得使用 PERMISSION_DENIED（请改用 UNAUTHENTICATED 来表示此类错误）。此错误代码并不意味着请求有效，或者请求的实体存在或满足其他先决条件。

HTTP 映射：403 Forbidden
UNAUTHENTICATED

请求没有相应操作的有效身份验证凭据。

HTTP 映射：401 Unauthorized
RESOURCE_EXHAUSTED

部分资源已用尽，可能是每用户配额不足，也可能是整个文件系统的存储空间已用完。

HTTP 映射：429 Too Many Requests
FAILED_PRECONDITION

操作被拒绝，因为系统未处于执行该操作所需的状态。例如，要删除的目录非空、将 rmdir 操作应用于非目录等等。

服务实现者可根据以下准则来确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE：

  • 如果客户端只能重试失败的调用，请使用 UNAVAILABLE。
  • 如果客户端应在更高级层执行重试，则使用 ABORTED。例如当客户端指定的“测试并设置”操作失败时，这意味着客户端应重启“读取-修改-写入”序列。
  • 如果客户端不得在系统状态明确修正前执行重试，则使用 FAILED_PRECONDITION。例如，如果因非空目录而导致“rmdir”失败，应返回 FAILED_PRECONDITION，因为客户端只能在目录中的文件删除之后执行重试。

HTTP 映射：400 Bad Request
ABORTED

操作已中止，通常是由于序列程序检查失败或事务中止等并发问题。

请参阅上述准则以确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE。

HTTP 映射：409 Conflict
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 Bad Request
UNIMPLEMENTED

操作在此服务中未实现或不受支持/未启用。

HTTP 映射：501 Not Implemented
INTERNAL

内部错误。这意味着底层系统所期望的一些不变量已损坏。此错误代码保留用于严重错误。

HTTP 映射：500 内部服务器错误
UNAVAILABLE

该服务目前不可用。这很可能是一种暂时情况，可以通过退避重试来纠正。 请注意，重试执行非幂等操作并非总是安全的。

请参阅上述准则以确定是选择 FAILED_PRECONDITION、ABORTED 还是 UNAVAILABLE。

HTTP 映射：503 Service Unavailable
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

 列出给定项目中给定位置的所有批处理作业。