feat: added Location API methods

Google APIs · copybara-github · commit 71673d86fb33 · 2022-11-16T18:56:29.000-08:00
docs: updated comments

PiperOrigin-RevId: 489094434
diff --git a/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_v1.yaml b/google/cloud/bigquery/datatransfer/v1/bigquerydatatransfer_v1.yaml
@@ -5,6 +5,7 @@ title: BigQuery Data Transfer API
 
 apis:
 - name: google.cloud.bigquery.datatransfer.v1.DataTransferService
+- name: google.cloud.location.Locations
 
 documentation:
   summary: |-
diff --git a/google/cloud/bigquery/datatransfer/v1/datatransfer.proto b/google/cloud/bigquery/datatransfer/v1/datatransfer.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -217,10 +217,12 @@ service DataTransferService {
 
   // Enroll data sources in a user project. This allows users to create transfer
   // configurations for these data sources. They will also appear in the
-  // ListDataSources RPC and as such, will appear in the BigQuery UI
-  // 'https://bigquery.cloud.google.com' (and the documents can be found at
-  // https://cloud.google.com/bigquery/bigquery-web-ui and
-  // https://cloud.google.com/bigquery/docs/working-with-transfers).
+  // ListDataSources RPC and as such, will appear in the
+  // [BigQuery UI](https://console.cloud.google.com/bigquery), and the documents
+  // can be found in the public guide for
+  // [BigQuery Web UI](https://cloud.google.com/bigquery/bigquery-web-ui) and
+  // [Data Transfer
+  // Service](https://cloud.google.com/bigquery/docs/working-with-transfers).
   rpc EnrollDataSources(EnrollDataSourcesRequest) returns (google.protobuf.Empty) {
     option (google.api.http) = {
       post: "/v1/{name=projects/*/locations/*}:enrollDataSources"
@@ -287,7 +289,7 @@ message DataSourceParameter {
   // For integer and double values specifies minimum allowed value.
   google.protobuf.DoubleValue min_value = 9;
 
-  // For integer and double values specifies maxminum allowed value.
+  // For integer and double values specifies maximum allowed value.
   google.protobuf.DoubleValue max_value = 10;
 
   // Deprecated. This field has no effect.
@@ -438,7 +440,7 @@ message GetDataSourceRequest {
 message ListDataSourcesRequest {
   // Required. The BigQuery project id for which data sources should be returned.
   // Must be in the form: `projects/{project_id}` or
-  // `projects/{project_id}/locations/{location_id}
+  // `projects/{project_id}/locations/{location_id}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -470,9 +472,9 @@ message ListDataSourcesResponse {
 }
 
 // A request to create a data transfer configuration. If new credentials are
-// needed for this transfer configuration, an authorization code must be
-// provided. If an authorization code is provided, the transfer configuration
-// will be associated with the user id corresponding to the authorization code.
+// needed for this transfer configuration, authorization info must be provided.
+// If authorization info is provided, the transfer configuration will be
+// associated with the user id corresponding to the authorization info.
 // Otherwise, the transfer configuration will be associated with the calling
 // user.
 message CreateTransferConfigRequest {
@@ -491,78 +493,99 @@ message CreateTransferConfigRequest {
   TransferConfig transfer_config = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Optional OAuth2 authorization code to use with this transfer configuration.
-  // This is required if new credentials are needed, as indicated by
-  // `CheckValidCreds`.
-  // In order to obtain authorization_code, please make a
-  // request to
-  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=<datatransferapiclientid>&scope=<data_source_scopes>&redirect_uri=<redirect_uri>
+  // This is required only if `transferConfig.dataSourceId` is 'youtube_channel'
+  // and new credentials are needed, as indicated by `CheckValidCreds`. In order
+  // to obtain authorization_code, make a request to the following URL:
+  // <pre class="prettyprint" suppresswarning="true">
+  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=authorization_code&client_id=<var>client_id</var>&scope=<var>data_source_scopes</var>
+  // </pre>
+  // * The <var>client_id</var> is the OAuth client_id of the a data source as
+  // returned by ListDataSources method.
+  // * <var>data_source_scopes</var> are the scopes returned by ListDataSources
+  // method.
   //
-  // * client_id should be OAuth client_id of BigQuery DTS API for the given
-  //   data source returned by ListDataSources method.
-  // * data_source_scopes are the scopes returned by ListDataSources method.
-  // * redirect_uri is an optional parameter. If not specified, then
-  //   authorization code is posted to the opener of authorization flow window.
-  //   Otherwise it will be sent to the redirect uri. A special value of
-  //   urn:ietf:wg:oauth:2.0:oob means that authorization code should be
-  //   returned in the title bar of the browser, with the page text prompting
-  //   the user to copy the code and paste it in the application.
+  // Note that this should not be set when `service_account_name` is used to
+  // create the transfer config.
   string authorization_code = 3;
 
-  // Optional version info. If users want to find a very recent access token,
-  // that is, immediately after approving access, users have to set the
-  // version_info claim in the token request. To obtain the version_info, users
-  // must use the "none+gsession" response type. which be return a
-  // version_info back in the authorization response which be be put in a JWT
-  // claim in the token request.
+  // Optional version info. This is required only if
+  // `transferConfig.dataSourceId` is not 'youtube_channel' and new credentials
+  // are needed, as indicated by `CheckValidCreds`. In order to obtain version
+  // info, make a request to the following URL:
+  // <pre class="prettyprint" suppresswarning="true">
+  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=version_info&client_id=<var>client_id</var>&scope=<var>data_source_scopes</var>
+  // </pre>
+  // * The <var>client_id</var> is the OAuth client_id of the a data source as
+  // returned by ListDataSources method.
+  // * <var>data_source_scopes</var> are the scopes returned by ListDataSources
+  // method.
+  //
+  // Note that this should not be set when `service_account_name` is used to
+  // create the transfer config.
   string version_info = 5;
 
-  // Optional service account name. If this field is set, transfer config will
-  // be created with this service account credentials. It requires that
-  // requesting user calling this API has permissions to act as this service
+  // Optional service account name. If this field is set, the transfer config
+  // will be created with this service account's credentials. It requires that
+  // the requesting user calling this API has permissions to act as this service
   // account.
+  //
+  // Note that not all data sources support service account credentials when
+  // creating a transfer config. For the latest list of data sources, read about
+  // [using service
+  // accounts](https://cloud.google.com/bigquery-transfer/docs/use-service-accounts).
   string service_account_name = 6;
 }
 
 // A request to update a transfer configuration. To update the user id of the
-// transfer configuration, an authorization code needs to be provided.
+// transfer configuration, authorization info needs to be provided.
 message UpdateTransferConfigRequest {
   // Required. Data transfer configuration to create.
   TransferConfig transfer_config = 1 [(google.api.field_behavior) = REQUIRED];
 
   // Optional OAuth2 authorization code to use with this transfer configuration.
-  // If it is provided, the transfer configuration will be associated with the
-  // authorizing user.
-  // In order to obtain authorization_code, please make a
-  // request to
-  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=<datatransferapiclientid>&scope=<data_source_scopes>&redirect_uri=<redirect_uri>
+  // This is required only if `transferConfig.dataSourceId` is 'youtube_channel'
+  // and new credentials are needed, as indicated by `CheckValidCreds`. In order
+  // to obtain authorization_code, make a request to the following URL:
+  // <pre class="prettyprint" suppresswarning="true">
+  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=authorization_code&client_id=<var>client_id</var>&scope=<var>data_source_scopes</var>
+  // </pre>
+  // * The <var>client_id</var> is the OAuth client_id of the a data source as
+  // returned by ListDataSources method.
+  // * <var>data_source_scopes</var> are the scopes returned by ListDataSources
+  // method.
   //
-  // * client_id should be OAuth client_id of BigQuery DTS API for the given
-  //   data source returned by ListDataSources method.
-  // * data_source_scopes are the scopes returned by ListDataSources method.
-  // * redirect_uri is an optional parameter. If not specified, then
-  //   authorization code is posted to the opener of authorization flow window.
-  //   Otherwise it will be sent to the redirect uri. A special value of
-  //   urn:ietf:wg:oauth:2.0:oob means that authorization code should be
-  //   returned in the title bar of the browser, with the page text prompting
-  //   the user to copy the code and paste it in the application.
+  // Note that this should not be set when `service_account_name` is used to
+  // update the transfer config.
   string authorization_code = 3;
 
   // Required. Required list of fields to be updated in this request.
   google.protobuf.FieldMask update_mask = 4 [(google.api.field_behavior) = REQUIRED];
 
-  // Optional version info. If users want to find a very recent access token,
-  // that is, immediately after approving access, users have to set the
-  // version_info claim in the token request. To obtain the version_info, users
-  // must use the "none+gsession" response type. which be return a
-  // version_info back in the authorization response which be be put in a JWT
-  // claim in the token request.
+  // Optional version info. This is required only if
+  // `transferConfig.dataSourceId` is not 'youtube_channel' and new credentials
+  // are needed, as indicated by `CheckValidCreds`. In order to obtain version
+  // info, make a request to the following URL:
+  // <pre class="prettyprint" suppresswarning="true">
+  // https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=version_info&client_id=<var>client_id</var>&scope=<var>data_source_scopes</var>
+  // </pre>
+  // * The <var>client_id</var> is the OAuth client_id of the a data source as
+  // returned by ListDataSources method.
+  // * <var>data_source_scopes</var> are the scopes returned by ListDataSources
+  // method.
+  //
+  // Note that this should not be set when `service_account_name` is used to
+  // update the transfer config.
   string version_info = 5;
 
-  // Optional service account name. If this field is set and
-  // "service_account_name" is set in update_mask, transfer config will be
-  // updated to use this service account credentials. It requires that
-  // requesting user calling this API has permissions to act as this service
+  // Optional service account name. If this field is set, the transfer config
+  // will be created with this service account's credentials. It requires that
+  // the requesting user calling this API has permissions to act as this service
   // account.
+  //
+  // Note that not all data sources support service account credentials when
+  // creating a transfer config. For the latest list of data sources, read about
+  // [using service
+  // accounts](https://cloud.google.com/bigquery-transfer/docs/use-service-accounts).
   string service_account_name = 6;
 }
 
@@ -621,7 +644,7 @@ message DeleteTransferRunRequest {
 
 // A request to list data transfers configured for a BigQuery project.
 message ListTransferConfigsRequest {
-  // Required. The BigQuery project id for which data sources
+  // Required. The BigQuery project id for which transfer configs
   // should be returned: `projects/{project_id}` or
   // `projects/{project_id}/locations/{location_id}`
   string parent = 1 [
@@ -844,8 +867,7 @@ message StartManualTransferRunsResponse {
 // A request to enroll a set of data sources so they are visible in the
 // BigQuery UI's `Transfer` tab.
 message EnrollDataSourcesRequest {
-  // The name of the project resource in the form:
-  // `projects/{project_id}`
+  // The name of the project resource in the form: `projects/{project_id}`
   string name = 1;
 
   // Data sources that are enrolled. It is required to provide at least one
diff --git a/google/cloud/bigquery/datatransfer/v1/transfer.proto b/google/cloud/bigquery/datatransfer/v1/transfer.proto
@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -133,7 +133,9 @@ message TransferConfig {
   // User specified display name for the data transfer.
   string display_name = 3;
 
-  // Data source id. Cannot be changed once data transfer is created.
+  // Data source ID. This cannot be changed once data transfer is created. The
+  // full list of available data source IDs can be returned through an API call:
+  // https://cloud.google.com/bigquery-transfer/docs/reference/datatransfer/rest/v1/projects.locations.dataSources/list
   string data_source_id = 5;
 
   // Parameters specific to each data source. For more information see the
