Conectar-se ao Apache Spark

Como administrador do BigQuery, é possível criar uma conexão para permitir que os analistas de dados executem procedimentos armazenados para o Apache Spark.

Antes de começar

Ative a API BigQuery Connection.

Ativar a API
Para receber as permissões necessárias para criar uma conexão do Spark, peça ao administrador para conceder a você o papel do IAM Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.
Opcional: para gerenciar seus metadados com o metastore do Dataproc, verifique se você criou um serviço do Dataproc Metastore.
Opcional: para conferir o histórico de jobs usando as interfaces da Web do servidor de histórico do Spark, verifique se você criou um servidor de histórico persistente do Dataproc (PHS, na sigla em inglês).

Considerações sobre o local

Ao escolher um local para os dados, pense no seguinte:

Multirregiões

É preciso especificar os recursos do Google Cloud localizados na mesma área geográfica:

Uma conexão na multirregião dos EUA do BigQuery pode fazer referência a um servidor de histórico do Spark ou a um metastore do Dataproc em qualquer região na área geográfica dos EUA, como us-central1, us-east4 ou us-west2.
Uma conexão na multirregião da UE do BigQuery pode fazer referência a um servidor de histórico do Spark ou a um metastore do Dataproc em estados de membros da União Europeia, como europe-north1 ou europe-west3.

Regiões únicas

Uma conexão em uma única região só pode fazer referência a recursos do Google Cloud na mesma região. Por exemplo, uma conexão na única região us-east4 pode fazer referência apenas a um servidor de histórico do Spark ou a um metastore do Dataproc em us-east4.

Criar conexões

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery
Para criar uma conexão, clique em adicionar Adicionar dados e clique em Conexões com fontes de dados externas.
Na lista Tipo de conexão, selecione Apache Spark.
No campo ID da conexão, insira um nome para a conexão, por exemplo, spark_connection.
Na lista Local dos dados, selecione uma região.

É possível criar uma conexão em regiões e multirregiões com suporte ao BigQuery. Para mais informações, consulte Considerações de localização.
Opcional: na lista Serviço do metastore, selecione um Metastore do Dataproc.
Opcional: no campo Cluster do servidor de histórico, insira um servidor de histórico persistente do Dataproc.
Clique em Criar conexão.
Clique em Ir para conexão.
No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa seguinte.

bq

Em um ambiente de linha de comando, use o comando bq mk para criar uma conexão:
```
bq mk --connection --connection_type='SPARK' \
 --properties=PROPERTIES \
 --project_id=PROJECT_ID \
 --location=LOCATION
 CONNECTION_ID
```
Substitua:
- PROPERTIES: um par de chave-valor para incluir parâmetros específicos da conexão no formato JSON
  
  Por exemplo:
```
--properties='{
"metastoreServiceConfig": {"metastoreService": "METASTORE_SERVICE_NAME"},
"sparkHistoryServerConfig": {"dataprocCluster": "DATAPROC_CLUSTER_NAME"}
}'
```
  Substitua:
  - METASTORE_SERVICE_NAME: o metastore do Dataproc com uma configuração de rede gRPC, por exemplo, projects/my-project-id/locations/us-central1/services/my-service.
    
    Para mais informações, veja como acessar os metadados armazenados do metastore do Hive usando um protocolo de endpoint.
  - DATAPROC_CLUSTER_NAME: a configuração do servidor de histórico do Spark, por exemplo, projects/my-project-id/regions/us-central1/clusters/my-cluster
    
    Para mais informações, consulte Criar um cluster do servidor do histórico persistente.
- PROJECT_ID: o ID do projeto do Google Cloud
- LOCATION: o local em que você quer armazenar a conexão, por exemplo, US
- CONNECTION_ID: o ID da conexão. Por exemplo, myconnection.
  
  Ao ver os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/.../locations/.../connections/myconnection.

Recupere e copie o ID da conta de serviço porque você precisará dele em outra etapa:

bq show --location=LOCATION --connection PROJECT_ID.LOCATION.CONNECTION_ID

O resultado será assim:

Connection myproject.us.myconnection

       name           type                    properties
---------------------- ------- ---------------------------------------------------
myproject.us.myconnection  SPARK   {"serviceAccountId": "bqserver@example.iam.gserviceaccount.com"}

Para saber mais sobre como gerenciar conexões, consulte Gerenciar conexões.

Conceder acesso à conta de serviço

Para permitir que um procedimento armazenado para o Apache Spark acesse seus recursos do Google Cloud, é necessário conceder as permissões de IAM necessárias à conta de serviço associada à conexão do procedimento armazenado. Também é possível usar a conta de serviço personalizada para acessar os dados.

Para ler e gravar dados de e para o BigQuery, você precisa conceder à conta de serviço as seguintes permissões do IAM:
- bigquery.tables.* nas tabelas do BigQuery
- bigquery.readsessions.* no seu projeto
O papel roles/bigquery.admin do IAM inclui as permissões necessárias para a conta de serviço ler e gravar dados no BigQuery.

Observação: se o procedimento armazenado gravar dados em um bucket temporário do Cloud Storage e carregar os dados do Cloud Storage no BigQuery, você precisa conceder à conta de serviço a permissão bigquery.jobs.create no seu projeto. Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso com o IAM.
Para ler e gravar dados de e para o Cloud Storage, conceda à conta de serviço a permissão storage.objects.* nos seus objetos do Cloud Storage.

O papel roles/storage.objectAdmin do IAM inclui as permissões necessárias para a conta de serviço ler e gravar dados no Cloud Storage e no Cloud Storage.
Se você especificar o metastore do Dataproc ao criar uma conexão, então para o BigQuery recuperar detalhes sobre a configuração do metastore, você precisará conceder à conta de serviço a permissão metastore.services.get ao Dataproc Metastore.

O papel predefinido roles/metastore.metadataViewer inclui a permissão necessária para a conta de serviço a fim de recuperar detalhes sobre a configuração do metastore.

Você também precisa conceder à conta de serviço o papel roles/storage.objectAdmin no bucket do Cloud Storage para que o procedimento armazenado possa acessar o diretório de armazenamento do Hive do metastore do Dataproc (hive.metastore.warehouse.dir). Se o procedimento armazenado executar operações no metastore, poderá ser necessário conceder permissões adicionais. Para mais informações sobre papéis e permissões do IAM no Dataproc Metastore, consulte Papéis e permissões predefinidos do Dataproc Metastore.
Se você especificar um servidor persistente de histórico do Dataproc ao criar uma conexão, será necessário conceder à conta de serviço os seguintes papéis:
- O papel roles/dataproc.viewer no servidor de histórico persistente do Dataproc que contém a permissão dataproc.clusters.get.
- O papel roles/storage.objectAdmin no bucket do Cloud Storage especificado para a propriedade spark:spark.history.fs.logDirectory ao criar o servidor de histórico persistente do Dataproc.
Para mais informações, consulte Servidor de histórico persistente do Dataproc e Papéis e permissões do Dataproc.

Compartilhar conexões com os usuários

Você pode conceder os seguintes papéis para permitir que os usuários consultem dados e gerenciem conexões:

roles/bigquery.connectionUser: permite aos usuários usar conexões para se conectar a fontes de dados externas e executar consultas nelas.
roles/bigquery.connectionAdmin: permite que os usuários gerenciem conexões.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Ir para o BigQuery

As conexões são listadas no projeto, em um grupo chamado Conexões externas.
No painel Explorer, clique no nome do seu projeto > Explorer > conexão.
No painel Detalhes, clique em Compartilhar para compartilhar uma conexão. Em seguida, siga estas etapas:
1. Na caixa de diálogo Permissões de conexão, compartilhe a conexão com outros principais adicionando ou editando principais.
2. Clique em Salvar.

bq

Não é possível compartilhar uma conexão com a ferramenta de linha de comando bq. Para compartilhar um recurso de conexão, use o console do Google Cloud ou o método da API BigQuery Connections para compartilhar uma conexão.

API

Consulte o método projects.locations.connections.setIAM na seção de referência da API REST BigQuery Connections e forneça uma instância do recurso policy.

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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");
    }
  }
}

A seguir

Saiba sobre diferentes tipos de conexão.
Saiba mais sobre como gerenciar conexões.
Saiba como criar um procedimento armazenado para o Apache Spark.
Saiba como gerenciar procedimentos armazenados.