软件包 google.cloud.bigquery.reservation.v1beta1

索引

ReservationService

借助此 API,用户可以管理其固定费率 BigQuery 预留。

预留以的形式向用户提供计算资源保证。槽是 BigQuery 中的计算容量单位,也是并行处理的基本单元。扫描多分区表时,单个槽处理表的单个分区中的数据。预留资源作为管理项目和位置的子资源存在,例如:projects/myproject/locations/US/reservations/reservationName。

容量承诺是为 BigQuery 作业购买计算容量的一种方法(以槽的形式),并且具有一定的承诺使用期。容量承诺资源作为管理项目和位置的子资源存在,例如:projects/myproject/locations/US/capacityCommitments/id。

CreateAssignment

rpc CreateAssignment(CreateAssignmentRequest) returns (Assignment)

如果用户对使用预留的项目和拥有此预留的项目没有“bigquery.admin”权限,则返回 google.rpc.Code.PERMISSION_DENIED。如果分配位置与预留位置不匹配,则返回 google.rpc.Code.INVALID_ARGUMENT

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

CreateReservation

rpc CreateReservation(CreateReservationRequest) returns (Reservation)

创建新的预留资源。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

DeleteAssignment

rpc DeleteAssignment(DeleteAssignmentRequest) returns (Empty)

删除分配。不会发生任何扩展。例如,organizationA 包含 project1 和 project2。存在预留 res1。系统之前已调用 CreateAssignment,并且明确创建了以下分配:<organizationA, res1> <project1, res1>。然后,删除 <organizationA, res1> 将不会影响 <project1, res1>。删除 <organizationA, res1> 后,来自 project1 的查询将仍然使用 res1,而来自 project2 的查询将使用按需模式。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

DeleteCapacityCommitment

rpc DeleteCapacityCommitment(DeleteCapacityCommitmentRequest) returns (Empty)

删除容量承诺。如果尝试在相应 commitment_end_time 之前删除容量承诺,则操作将失败并显示错误代码 google.rpc.Code.FAILED_PRECONDITION

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

DeleteReservation

rpc DeleteReservation(DeleteReservationRequest) returns (Empty)

删除预留。如果预留已有分配,则返回 google.rpc.Code.FAILED_PRECONDITION

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

GetBiReservation

rpc GetBiReservation(GetBiReservationRequest) returns (BiReservation)

检索 BI 预留。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

GetCapacityCommitment

rpc GetCapacityCommitment(GetCapacityCommitmentRequest) returns (CapacityCommitment)

返回有关容量承诺的信息。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

GetReservation

rpc GetReservation(GetReservationRequest) returns (Reservation)

返回预留的相关信息。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

ListAssignments

rpc ListAssignments(ListAssignmentsRequest) returns (ListAssignmentsResponse)

列出分配。系统将仅返回明确创建的分配。例如,organizationA 包含 project1 和 project2。存在预留 res1。系统之前已调用 CreateAssignment,并且明确创建了以下分配:<organizationA, res1> <project1, res1>。然后,此 API 将仅返回预留 res1 的上述两个分配,且不会发生展开/合并。通配符“-”可用于请求中的预留。在这种情况下,所有分配都属于指定项目,并将列出位置。注意,“-”不能用于项目或位置。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

ListCapacityCommitments

rpc ListCapacityCommitments(ListCapacityCommitmentsRequest) returns (ListCapacityCommitmentsResponse)

列出管理项目的所有容量承诺。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

ListReservations

rpc ListReservations(ListReservationsRequest) returns (ListReservationsResponse)

列出项目在指定位置的所有预留。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

MergeCapacityCommitments

rpc MergeCapacityCommitments(MergeCapacityCommitmentsRequest) returns (CapacityCommitment)

将同一计划的容量承诺合并为一个。产生的容量承诺采用两个时间中较长的 commitment_end_time。如果尝试合并不同方案的容量承诺,则操作将失败并显示错误代码 google.rpc.Code.FAILED_PRECONDITION

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

MoveAssignment

rpc MoveAssignment(MoveAssignmentRequest) returns (Assignment)

移动新预留名下的分配。客户可以通过删除现有的分配,然后在新预留下再创建一个分配来执行此操作,但此方法是事务性方法,目的是确保分配对象始终具有关联的预留。如果不采用此方法,客户可能会看到一些意料之外的查询按需运行。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

SearchAssignments

rpc SearchAssignments(SearchAssignmentsRequest) returns (SearchAssignmentsResponse)

查找指定区域中指定资源的分配。如果请求是针对某个项目的:1) 该项目中如果存在创建的分配,则返回其中的分配。2) 否则,将返回在最近祖先实体中创建的分配。3) 不同 JobType 的分配将全部返回。如果请求是针对某个文件夹的,则应用相同的逻辑。如果请求针对某个组织,则返回在该组织中创建的分配(组织没有祖先实体)。此方法与 ListAssignments 相比,存在一些行为差异:1) 此 API 会验证分配对象的权限。2) 此 API 会执行层次结构查找(项目 -> 文件夹 -> 组织)。3) 此处的父级是 projects/*/locations/*,而不是 projects/*/locations/*reservations/*。注意,“-”不能用于项目或位置。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

SplitCapacityCommitment

rpc SplitCapacityCommitment(SplitCapacityCommitmentRequest) returns (SplitCapacityCommitmentResponse)

将容量承诺拆分为方案和 commitment_end_time 都相同的两个承诺。为此,一种常见的使用情况是执行降级,例如为了从 10000 个槽降级到 8000 个槽,可以将 10000 个槽的容量承诺拆分成 2000 个槽的容量承诺和 8000 个槽的容量承诺,将第一个承诺的方案更改为“灵活”,然后将其删除。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

UpdateBiReservation

rpc UpdateBiReservation(UpdateBiReservationRequest) returns (BiReservation)

更新 BI 预留。仅更新 field_mask 中指定的字段。单例 BI 预留始终存在,且默认大小为 0。如需预留 BI 容量,需要将其更新为大于 0 的值。如需释放 BI 容量,预留大小必须设置为 0。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

UpdateCapacityCommitment

rpc UpdateCapacityCommitment(UpdateCapacityCommitmentRequest) returns (CapacityCommitment)

更新现有容量承诺。

只能更新方案和 renewal_plan 字段。方案只能更改为承诺期更长的方案。尝试更改为承诺期更短的方案将失败,并显示错误代码 google.rpc.Code.FAILED_PRECONDITION

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

UpdateReservation

rpc UpdateReservation(UpdateReservationRequest) returns (Reservation)

更新现有的预留资源。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅身份验证概览

Assignment

借助分配,项目可以使用指定预留提供的槽来提交特定类型的作业。

字段
name

string

仅限输出。资源的名称。例如:projects/myproject/locations/US/reservations/team1-prod/assignments/123。

assignee

string

将使用预留的资源。例如:projects/myproject、folders/123、organizations/456。

job_type

JobType

将使用预留的作业的类型。

state

State

仅供输出。分配的状态。

JobType

作业的类型,可在使用预留时指定。

枚举
JOB_TYPE_UNSPECIFIED 无效类型。使用此值的请求将被拒绝,错误代码为 google.rpc.Code.INVALID_ARGUMENT
PIPELINE 项目中的流水线(加载/导出)作业将使用预留。
QUERY 项目中的查询作业将使用预留。

State

如果不存在有效容量承诺,则分配将保持“PENDING”状态。当一些容量承诺生效时,分配状态会变为“ACTIVE”。

枚举
STATE_UNSPECIFIED 状态值无效。
PENDING 如果相关分配处于待处理状态,则系统会按需执行分配对象提交的查询。
ACTIVE 分配已准备就绪。

BiReservation

表示 BI 预留。

字段
name

string

单例 BI 预留的资源名称。预留名称的格式为 projects/{project_id}/locations/{location_id}/bireservation

update_time

Timestamp

仅供输出。预留的上次更新时间戳。

size

int64

预留的大小,以字节为单位。

CapacityCommitment

容量承诺是为 BigQuery 作业购买计算容量的一种方法(以槽的形式),并且具有一定的承诺使用期。默认情况下,月度和年度承诺会续订。您只能移除灵活类型的承诺。如需移除月度或年度承诺,需要先将承诺方案更改为灵活类型。

容量承诺资源作为管理项目的子资源存在。

字段
name

string

仅供输出。容量承诺的资源名称,例如:projects/myproject/locations/US/capacityCommitments/123

slot_count

int64

此承诺中的槽数。

plan

CommitmentPlan

容量承诺的承诺方案。

state

State

仅供输出。承诺的状态。

commitment_end_time

Timestamp

仅供输出。当前承诺期的结束时间。它仅适用于 ACTIVE 状态的容量承诺。

failure_status

Status

仅供输出。对于 FAILED 状态的承诺方案,请提供失败的原因。

renewal_plan

CommitmentPlan

此容量承诺在 commitment_end_time 后转换为的方案。更改方案后,系统会根据承诺方案延长承诺期。仅适用于 MONTHLY 和 ANNUAL 类型的承诺。

CommitmentPlan

承诺方案定义当前承诺期。容量承诺在其承诺期内无法删除。

枚举
COMMITMENT_PLAN_UNSPECIFIED 方案值无效。使用此值的请求将被拒绝,错误代码为 google.rpc.Code.INVALID_ARGUMENT
FLEX 灵活类型的承诺的承诺期为变为 ACTIVE 状态后的 1 分钟。1 分钟过后,这些承诺将不再处于承诺期,可以随时移除。
MONTHLY 月度承诺的承诺期为变为 ACTIVE 状态后的 30 天。
ANNUAL 年度承诺的承诺期为变为 ACTIVE 状态后的 365 天。

State

容量承诺可以立即变为 ACTIVE 状态,也可以从 PENDING 状态转换为 ACTIVE 或 FAILED 状态。

枚举
STATE_UNSPECIFIED 状态值无效。
PENDING 容量承诺正在等待预配。待处理的容量承诺不会添加到父级 slot_capacity。
ACTIVE 槽预配完成后,容量承诺即生效。系统会将 slot_count 添加到父级 slot_capacity。
FAILED 后端未能激活容量承诺。

CreateAssignmentRequest

ReservationService.CreateAssignment 的请求。注意:相关分配对象需要具有“bigquery.reservationAssignments.create”权限。

字段
parent

string

必需。分配的父资源名称,例如:projects/myproject/locations/US/reservations/team1-prod

必须对指定的资源 parent 具有以下 Google IAM 权限才能进行授权:

  • bigquery.reservationAssignments.create
assignment

Assignment

需要创建的分配资源。

CreateReservationRequest

ReservationService.CreateReservation 的请求。

字段
parent

string

必需。项目、位置。例如,projects/myproject/locations/US

reservation_id

string

预留 ID。此字段只能包含小写字母数字字符或短划线。长度上限为 64 个字符。

reservation

Reservation

需要创建的新预留的内容。

DeleteAssignmentRequest

ReservationService.DeleteAssignment 的请求。注意:相关分配对象需要具有“bigquery.reservationAssignments.delete”权限。

字段
name

string

必需。资源的名称,例如:projects/myproject/locations/US/reservations/team1-prod/assignments/123

必须对指定的资源 name 具有以下 Google IAM 权限才能进行授权:

  • bigquery.reservationAssignments.delete

DeleteCapacityCommitmentRequest

ReservationService.DeleteCapacityCommitment 的请求。

字段
name

string

必需。需要删除的容量承诺的资源名称。例如,projects/myproject/locations/US/capacityCommitments/123

DeleteReservationRequest

ReservationService.DeleteReservation 的请求。

字段
name

string

必需。需要检索的预留的资源名称。例如,projects/myproject/locations/US/reservations/team1-prod

GetBiReservationRequest

获取单例 BI 预留的请求。

字段
name

string

必需。请求的预留的名称,例如:projects/{project_id}/locations/{location_id}/bireservation

必须对指定的资源 name 具有以下 Google IAM 权限才能进行授权:

  • bi.reservations.get

GetCapacityCommitmentRequest

ReservationService.GetCapacityCommitment 的请求。

字段
name

string

必需。需要检索的容量承诺的资源名称。例如,projects/myproject/locations/US/capacityCommitments/123

GetReservationRequest

ReservationService.GetReservation 的请求。

字段
name

string

必需。需要检索的预留的资源名称。例如,projects/myproject/locations/US/reservations/team1-prod

ListAssignmentsRequest

ReservationService.ListAssignments 的请求。

字段
parent

string

必需。父级资源名称,例如:projects/myproject/locations/US/reservations/team1-prod 或 projects/myproject/locations/US/reservations/-

必须对指定的资源 parent 具有以下 Google IAM 权限才能进行授权:

  • bigquery.reservationAssignments.list
page_size

int32

需要返回的最大项数。

page_token

string

从上一个 List 请求返回的 next_page_token 值(如果有)。

ListAssignmentsResponse

ReservationService.ListAssignments 的响应。

字段
assignments[]

Assignment

向用户显示的分配列表。

next_page_token

string

用于检索下一页结果的令牌。如果列表中没有更多结果,则为空。

ListCapacityCommitmentsRequest

ReservationService.ListCapacityCommitments 的请求。

字段
parent

string

必需。父级预留的资源名称,例如:projects/myproject/locations/US

page_size

int32

需要返回的最大项数。

page_token

string

从上一个 List 请求返回的 next_page_token 值(如果有)。

ListCapacityCommitmentsResponse

ReservationService.ListCapacityCommitments 的响应。

字段
capacity_commitments[]

CapacityCommitment

用户可见容量承诺的列表。

next_page_token

string

用于检索下一页结果的令牌。如果列表中没有更多结果,则为空。

ListReservationsRequest

ReservationService.ListReservations 的请求。

字段
parent

string

必需。包含项目和位置的父资源名称,例如:“projects/myproject/locations/US”

page_size

int32

需要返回的最大项数。

page_token

string

从上一个 List 请求返回的 next_page_token 值(如果有)。

filter

string

可用于根据名称、容量等过滤掉预留,例如:filter="reservation.slot_capacity > 200"、filter="reservation.name = "*dev/*"" 此处可以查看高级过滤语法。

ListReservationsResponse

ReservationService.ListReservations 的响应。

字段
reservations[]

Reservation

向用户显示的预留列表。

next_page_token

string

用于检索下一页结果的令牌。如果列表中没有更多结果,则为空。

MergeCapacityCommitmentsRequest

ReservationService.MergeCapacityCommitments 的请求。

字段
parent

string

用于标识管理项目和位置的父资源,例如 projects/myproject/locations/us

capacity_commitment_ids[]

string

要合并的容量承诺的 ID。这些容量承诺必须位于父级中指定的管理项目和位置下。

MoveAssignmentRequest

ReservationService.MoveAssignment 的请求。注意:destination_id 需要具有“bigquery.reservationAssignments.create”权限。注意:相关分配对象需要具有“bigquery.reservationAssignments.create”和“bigquery.reservationAssignments.delete”权限。

字段
name

string

必需。分配的资源名称,例如:projects/myproject/locations/US/reservations/team1-prod/assignments/123

必须对指定的资源 name 具有以下 Google IAM 权限才能进行授权:

  • bigquery.reservationAssignments.delete
destination_id

string

新的预留 ID,例如,projects/myotherproject/locations/US/reservations/team2-prod

预留

预留是一种机制,用于保证用户有可用的槽。

字段
name

string

预留的资源名称,例如,“projects/*/locations/*/reservations/team1-prod”。

slot_capacity

int64

此预留可用的槽数下限。槽是 BigQuery 中的计算容量单位,也是并行处理的单位。如果 ignore_idle_slots 设置为 false,则使用此预留的查询可能会在运行时使用更多槽。如果新预留的槽容量超过了父级槽容量,或者新预留及其同级预留的总槽容量超过了父级槽容量,请求将会失败并返回 google.rpc.Code.RESOURCE_EXHAUSTED

ignore_idle_slots

bool

如果为 false,则使用此预留的任何查询都将使用同一管理项目中其他预留的空闲槽。如果为 true,则使用此预留的查询将按上述指定的槽容量上限来执行。

SearchAssignmentsRequest

ReservationService.SearchAssignments 的请求。注意:相关分配对象需要具有“bigquery.reservationAssignments.search”权限。

字段
parent

string

必需。管理项目的资源名称(包含项目和位置),例如:“projects/myproject/locations/US”。

query

string

请在查询中指定资源名称作为分配对象。例如:“assignee=projects/myproject”、“assignee=folders/123”、“assignee=organizations/456”

page_size

int32

需要返回的最大项数。

page_token

string

从上一个 List 请求返回的 next_page_token 值(如果有)。

SearchAssignmentsResponse

ReservationService.SearchAssignments 的响应。

字段
assignments[]

Assignment

向用户显示的分配列表。

next_page_token

string

用于检索下一页结果的令牌。如果列表中没有更多结果,则为空。

SplitCapacityCommitmentRequest

ReservationService.SplitCapacityCommitment 的请求。

字段
name

string

必需。资源名称,例如:projects/myproject/locations/US/capacityCommitments/123

必须对指定的资源 name 具有以下 Google IAM 权限才能进行授权:

  • bigquery.capacityCommitments.update
slot_count

int64

拆分后容量承诺中的槽数。

SplitCapacityCommitmentResponse

ReservationService.SplitCapacityCommitment 的响应。

字段
first

CapacityCommitment

第一个容量承诺,拆分结果。

second

CapacityCommitment

第二个容量承诺,拆分结果。

UpdateBiReservationRequest

更新 BI 预留的请求。

字段
reservation

BiReservation

需要更新的预留。

必须对指定的资源 reservation 具有以下 Google IAM 权限才能进行授权:

  • bi.reservations.update
update_mask

FieldMask

此请求中要更新的字段列表。

UpdateCapacityCommitmentRequest

ReservationService.UpdateCapacityCommitment 的请求。

字段
capacity_commitment

CapacityCommitment

需要更新的容量承诺的内容。

update_mask

FieldMask

要更新的一组字段的标准字段掩码。

UpdateReservationRequest

ReservationService.UpdateReservation 的请求。

字段
reservation

Reservation

需要更新的预留的内容。

update_mask

FieldMask

要更新的一组字段的标准字段掩码。