Administra conexiones

En este documento, se describe cómo ver, enumerar, compartir, editar, borrar y solucionar problemas de una conexión de BigQuery.

Como administrador de BigQuery, puedes crear y administrar conexiones que se usan para conectarse a servicios y fuentes de datos externas. Los analistas de BigQuery usan estas conexiones para enviar consultas a fuentes de datos externas sin mover o copiar datos a BigQuery. Puedes crear los siguientes tipos de conexiones:

Conexiones de Amazon S3
Conexiones de Apache Spark
Conexiones de Blob Storage
Conexiones de recursos de Cloud para conectarse a los datos de Cloud Storage e implementar funciones remotas
Conexiones de Spanner
Conexiones de Cloud SQL

Antes de comenzar

Habilita la API de conexión de BigQuery.

Habilitar la API
Asegúrate de que puedes ver una lista de cuentas de servicio en el proyecto. BigQuery crea y usa una cuenta de servicio para conectarse a tu fuente de datos externa. Cuando creas una conexión, se crea una cuenta de servicio de la administración de identidades y accesos (IAM) administrada por Google Cloud en tu nombre. Para ver la cuenta de servicio conectada a una conexión en particular, consulta los detalles de la conexión.

Roles obligatorios

Para obtener los permisos que necesitas a fin de administrar las conexiones, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Ver detalles de conexión: Usuario de conexión de BigQuery (roles/bigquery.connectionUser) en tu conjunto de datos
Enumerar todas las conexiones: Usuario de conexión de BigQuery (roles/bigquery.connectionUser) en tu conjunto de datos
Compartir una conexión: Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en tu conexión
Editar una conexión: Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en tu conexión
Borrar una conexión: Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en tu conexión

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas de este documento. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

Ver detalles de conexión: bigquery.connections.get
Enumerar todas las conexiones: bigquery.connections.list
Editar y borrar una conexión: bigquery.connections.update
Compartir una conexión: bigquery.connections.setIamPolicy

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Enumerar todas las conexiones

Selecciona una de las opciones siguientes:

Console

Ve a la página de BigQuery.

Ir a BigQuery

Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.
En el panel Explorador, haz clic en el nombre del proyecto > Conexiones externas para ver una lista de todas las conexiones.

bq

Usa el comando bq ls y especifica la marca --connection. De manera opcional, especifica las marcas --project_id y --location para identificar el proyecto y la ubicación de las conexiones que se enumerarán.

bq ls --connection --project_id=PROJECT_ID --location=REGION

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud
REGION: La región de conexión

API

Usa el método projects.locations.connections.list en la sección de referencia de la API de REST.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.connection.v1.ListConnectionsRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to get list of connections
public class ListConnections {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    listConnections(projectId, location);
  }

  static void listConnections(String projectId, String location) throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      LocationName parent = LocationName.of(projectId, location);
      int pageSize = 10;
      ListConnectionsRequest request =
          ListConnectionsRequest.newBuilder()
              .setParent(parent.toString())
              .setPageSize(pageSize)
              .build();
      client
          .listConnections(request)
          .iterateAll()
          .forEach(con -> System.out.println("Connection Id :" + con.getName()));
    }
  }
}

Ver detalles de conexión

Después de crear una conexión, puedes obtener información sobre la configuración de tu conexión. La configuración incluye los valores que proporcionaste cuando creaste la transferencia.

Selecciona una de las opciones siguientes:

Console

Ve a la página de BigQuery.

Ir a BigQuery

Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.
En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.

bq

Usa el comando bq show y especifica la marca --connection. De manera opcional, califica el ID de conexión con el ID del proyecto y la región de la conexión.

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud
REGION: La región de conexión
CONNECTION_I: el ID de conexión

API

Usa el método projects.locations.connections.get en la sección de referencia de la API de REST.

Java

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.GetConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to get connection
public class GetConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    getConnection(projectId, location, connectionId);
  }

  static void getConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionId);
      GetConnectionRequest request =
          GetConnectionRequest.newBuilder().setName(name.toString()).build();
      Connection response = client.getConnection(request);
      System.out.println("Connection info retrieved successfully :" + response.getName());
    }
  }
}

Puedes otorgar los siguientes roles para permitir que los usuarios consulten datos y administren conexiones:

roles/bigquery.connectionUser: Permite que los usuarios usen conexiones para conectarse con fuentes de datos externas y ejecutar consultas en ellas.
roles/bigquery.connectionAdmin: Permite que los usuarios administren conexiones.

Para obtener más información sobre los roles y los permisos de IAM en BigQuery, consulta Roles y permisos predefinidos.

Selecciona una de las opciones siguientes:

Console

Ve a la página de BigQuery.

Ir a BigQuery

Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.
En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.
En el panel Detalles, haz clic en Compartir para compartir una conexión. A continuación, sigue estos pasos:
1. En el cuadro de diálogo Permisos de conexión, agrega o edita las principales para compartir la conexión con otros principales.
2. Haz clic en Guardar.

bq

No puedes compartir una conexión con la herramienta de línea de comandos de bq. Para compartir una conexión, usa la consola de Google Cloud o el método de la API de conexiones de BigQuery.

API

Consulta el método projects.locations.connections.setIAM en la sección de referencia de la API de REST de las conexiones de BigQuery y proporciona una instancia del recurso policy.

Java

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

Editar una conexión

Una conexión usa las credenciales del usuario que la creó. Si necesitas cambiar el usuario que está conectado a una conexión, puedes actualizar las credenciales del usuario. Esto es útil si el usuario que creó la conexión ya no está en tu organización.

No puedes editar los siguientes elementos de un recurso de conexión:

Tipo de conexión
ID de la conexión
Ubicación

Selecciona una de las opciones siguientes:

Console

Ve a la página de BigQuery.

Ir a BigQuery

Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.
En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.
En el panel Detalles, para editar los detalles, haz clic en Editar detalles. A continuación, sigue estos pasos:
1. En el cuadro de diálogo Editar conexión, edita los detalles de la conexión, incluidas las credenciales del usuario.
2. Haz clic en Actualizar conexión.

bq

Ingresa el comando bq update y proporciona la marca de conexión --connection. Se requiere el connection_id completamente calificado.

  bq update --connection --connection_type='CLOUD_SQL'
      --properties='{"instanceId" : "INSTANCE",
      "database" : "DATABASE", "type" : "MYSQL" }'
      --connection_credential='{"username":"USERNAME", "password":"PASSWORD"}'
      PROJECT.REGION.CONNECTION_ID

Reemplaza lo siguiente:

INSTANCE: La instancia de Cloud SQL
DATABASE: El nombre de la base de datos
USERNAME: El nombre de usuario de tu base de datos de Cloud SQL
PASSWORD: La contraseña de tu base de datos de Cloud SQL
PROJECT: El ID del proyecto de Google Cloud
REGION: La región de conexión
CONNECTION_ID: el ID de conexión

Por ejemplo, mediante el siguiente comando, se actualiza la conexión en un proyecto con el ID federation-test y el ID de conexión test-mysql.

bq update --connection --connection_type='CLOUD_SQL'
    --properties='{"instanceId" : "federation-test:us-central1:new-mysql",
    "database" : "imdb2", "type" : "MYSQL" }'
    --connection_credential='{"username":"my_username",
    "password":"my_password"}' federation-test.us.test-mysql

API

Consulta el método projects.locations.connections.patch en la sección de referencia de la API de REST y proporciona una instancia de connection.

Java

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.UpdateConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;

// Sample to update connection
public class UpdateConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    String description = "MY_DESCRIPTION";
    Connection connection = Connection.newBuilder().setDescription(description).build();
    updateConnection(projectId, location, connectionId, connection);
  }

  static void updateConnection(
      String projectId, String location, String connectionId, Connection connection)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionId);
      FieldMask updateMask = FieldMaskUtil.fromString("description");
      UpdateConnectionRequest request =
          UpdateConnectionRequest.newBuilder()
              .setName(name.toString())
              .setConnection(connection)
              .setUpdateMask(updateMask)
              .build();
      Connection response = client.updateConnection(request);
      System.out.println("Connection updated successfully :" + response.getDescription());
    }
  }
}

Borrar una conexión

Selecciona una de las opciones siguientes:

Console

Ve a la página de BigQuery.

Ir a BigQuery

Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.
En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.
En el panel Detalles, haz clic en Borrar para borrar la conexión.
En el cuadro de diálogo ¿Borrar conexión?, ingresa delete para confirmar la eliminación.
Haz clic en Borrar.

bq

Ingresa el comando bq rm y proporciona la marca de conexión --connection. Se requiere el connection_id completamente calificado.

bq rm --connection PROJECT_ID.REGION.CONNECTION_ID

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto de Google Cloud
REGION: La región de conexión
CONNECTION_ID: el ID de conexión

API

Consulta el método projects.locations.connections.delete en la sección de referencia de la API de REST.

Java

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigquery.connection.v1.DeleteConnectionRequest;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

// Sample to delete a connection
public class DeleteConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionName = "MY_CONNECTION_NAME";
    deleteConnection(projectId, location, connectionName);
  }

  static void deleteConnection(String projectId, String location, String connectionName)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ConnectionName name = ConnectionName.of(projectId, location, connectionName);
      DeleteConnectionRequest request =
          DeleteConnectionRequest.newBuilder().setName(name.toString()).build();
      client.deleteConnection(request);
      System.out.println("Connection deleted successfully");
    }
  }
}

¿Qué sigue?

Aprende a usar funciones remotas.
Aprende a usar procedimientos almacenados para Apache Spark.

Administra conexiones

Antes de comenzar

Roles obligatorios

Permisos necesarios

Enumerar todas las conexiones

Console

bq

API

Java

Ver detalles de conexión

Console

bq

API

Java

Compartir una conexión con los usuarios

Console

bq

API

Java

Editar una conexión

Console

bq

API

Java

Borrar una conexión

Console

bq

API

Java

¿Qué sigue?