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

索引

ReservationService

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

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

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

CreateAssignment

rpc CreateAssignment(CreateAssignmentRequest) returns (Assignment)

创建一个分配对象,该对象允许给定项目使用指定预留提供的槽来提交特定类型的作业。

目前,资源(项目、文件夹、组织)的每个(作业类型、位置)组合只能有一个分配,并且该预留将用于匹配类型的所有作业。

您可以在不同级层的项目、文件夹或组织层次结构上创建不同的分配。在查询执行期间,系统会按照项目、文件夹和组织级层的顺序查找分配。找到的第一个分配将应用于查询。

创建分配时,较高级层是否存在其他分配无关紧要。

示例:

  • 组织 organizationA 包含 project1project2 两个项目。
  • 可以为所有三个实体(organizationAproject1project2)创建分配,并将其映射到相同或不同的预留。

如果用户对使用预留的项目和拥有此预留的项目没有“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

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

CreateCapacityCommitment

rpc CreateCapacityCommitment(CreateCapacityCommitmentRequest) returns (CapacityCommitment)

创建新的容量承诺资源。

授权范围

需要以下 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 包含 project1project2 两个项目。
  • 存在预留 res1 且之前已创建。
  • 之前已使用 CreateAssignment 定义实体和预留之间的以下关联:<organizationA, res1><project1, res1>

在此示例中,删除 <organizationA, res1> 分配不会影响另一个分配 <project1, 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 包含 project1project2 两个项目。
  • 存在预留 res1 且之前已创建。
  • 之前已使用 CreateAssignment 定义实体和预留之间的以下关联:<organizationA, res1><project1, res1>

在此示例中,ListAssignments 将仅返回预留 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 个槽的容量承诺。然后,将第一个承诺的方案改为 FLEX,再将其删除。

授权范围

需要以下 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)

更新现有容量承诺。

只能更新 planrenewal_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/myprojectfolders/123organizations/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 后转换为的方案。更改方案后,系统会根据承诺方案延长承诺期。仅适用于 ANNUAL 和 TRIAL 类型的承诺。

CommitmentPlan

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

枚举
COMMITMENT_PLAN_UNSPECIFIED 方案值无效。使用此值的请求将被拒绝,错误代码为 google.rpc.Code.INVALID_ARGUMENT
FLEX 灵活类型的承诺的承诺期为变为 ACTIVE 状态后的 1 分钟。之后,这些承诺将不再处于承诺期,可以随时移除。
TRIAL 试用承诺的承诺期为变为 ACTIVE 状态后的 182 天。之后,系统会根据 renewal_plan 将其转换为新承诺。试用承诺的默认 renewal_plan 为“灵活”,因此可在承诺期结束后立即删除。
MONTHLY 月度承诺的承诺期为变为 ACTIVE 状态后的 30 天。之后,这些承诺将不再处于承诺期,可以随时移除。
ANNUAL 年度承诺的承诺期为变为 ACTIVE 状态后的 365 天。之后,系统会根据 renewal_plan 将其转换为新承诺。

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 具有以下 IAM 权限才能进行授权:

  • bigquery.reservationAssignments.create
assignment

Assignment

要创建的分配资源。

CreateCapacityCommitmentRequest

ReservationService.CreateCapacityCommitment 的请求。

字段
parent

string

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

capacity_commitment

CapacityCommitment

需要创建的容量承诺的内容。

enforce_single_admin_project_per_org

bool

如果为 true,则组织中的其他项目具有容量承诺时,该请求会失败。

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 具有以下 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 具有以下 IAM 权限才能进行授权:

  • bigquery.bireservations.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 具有以下 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 值(如果有)。

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 具有以下 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 中的计算容量单位,也是并行处理的单位。

如果 ignoreIdleSlots 设置为 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 具有以下 IAM 权限才能进行授权:

  • bigquery.capacityCommitments.update
slot_count

int64

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

SplitCapacityCommitmentResponse

ReservationService.SplitCapacityCommitment 的响应。

字段
first

CapacityCommitment

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

second

CapacityCommitment

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

UpdateBiReservationRequest

更新 BI 预留的请求。

字段
bi_reservation

BiReservation

要更新的预留。

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

  • bigquery.bireservations.update
update_mask

FieldMask

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

UpdateCapacityCommitmentRequest

ReservationService.UpdateCapacityCommitment 的请求。

字段
capacity_commitment

CapacityCommitment

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

update_mask

FieldMask

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

UpdateReservationRequest

ReservationService.UpdateReservation 的请求。

字段
reservation

Reservation

需要更新的预留的内容。

update_mask

FieldMask

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