Conecte-se a um local externo do Google Cloud Storage (GCS)

Esta página descreve como se conectar a um local externo do Google Cloud Storage (GCS). Após concluir essa conexão, você pode controlar o acesso a esses objetos do GCS usando o Unity Catalog.

Para se conectar com sucesso a um caminho de bucket do GCS, você precisa de dois objetos protegíveis do Unity Catalog. A primeira é uma credencial de armazenamento, que especifica uma IAM role que permite acesso ao bucket GCS . Você precisa dessa credencial de armazenamento para o segundo objeto necessário: um local externo, que define o caminho para o local de armazenamento do GCS e as credenciais necessárias para acessar esse local.

Requisitos

No Databricks:

• Um workspace do Databricks ativado para o Unity Catalog.
• CREATE STORAGE CREDENTIAL privilégio no metastore do Unity Catalog anexado ao workspace. Os administradores de contas e administradores do metastore têm esse privilégio por padrão.
• CREATE EXTERNAL LOCATION privilégio no metastore do Unity Catalog e na credencial de armazenamento referenciada pelo local externo. Os administradores do Metastore e workspace têm esse privilégio por default.

Na sua conta do Google Cloud:

• Um balde GCS. Para evitar cobranças de saída, isso deve estar na mesma região do workspace do qual você deseja acessar os dados.

  • Os caminhos de localização externa devem conter apenas caracteres ASCII padrão (letras A–Z, a–z, dígitos 0–9 e símbolos comuns como /, _, -).
  • O namespace hierárquico (HNS) do Google Cloud Storage não é compatível com locais externos. Desabilite o namespace hierárquico antes de criar um local externo.

• Permissão para modificar a política de acesso para esse bucket.

Crie uma credencial de armazenamento que acesse o GCS

Para criar uma credencial de armazenamento para acesso a um bucket do GCS, você concede ao Unity Catalog a capacidade de ler e gravar no bucket atribuindo um IAM role nesse bucket a uma conta de serviço do Google Cloud gerada pelo Databricks.

Gerar uma account serviço em nuvem do Google usando o Catalog Explorer

1. Faça login em seu workspace do Databricks habilitado para o Unity Catalog como um usuário que tenha a permissão CREATE STORAGE CREDENTIAL no metastore.

2. Na barra lateral, clique em Catálogo .

3. Na página Acesso rápido , clique no botão Dados externos > , vá para a tab Credenciais e selecione Criar credencial .

4. Selecione um Tipo de credencial da conta de serviçoGCP .

5. Digite um nome de credencial de armazenamento e um comentário opcional.

6. (Opcional) Se você quiser que os usuários tenham acesso somente leitura aos locais externos que usam essa credencial de armazenamento, clique em Opções avançadas e selecione Limitar ao uso somente leitura . Para obter mais informações, consulte Marcar uma credencial de armazenamento como somente leitura.

7. Clique em Criar .

   O Databricks cria a credencial de armazenamento e gera uma conta de serviço do Google Cloud.

8. Na caixa de diálogo Credencial criada , anote o ID account serviço, que está no formato de um endereço email , e clique em Concluído .

9. (Opcional) Vincule a credencial de armazenamento a workspaces específicos.

   Por default, qualquer usuário privilegiado pode usar a credencial de armazenamento em qualquer workspace anexado ao metastore. Se você quiser permitir acesso somente de um espaço de trabalho específico, vá até a tab espaço de trabalho e atribua o espaço de trabalho. Consulte Atribuir uma credencial de armazenamento a um espaço de trabalho específico.

Configurar permissões para a accountde serviço

Agora você tem uma credencial de armazenamento no Databricks associada a uma account de serviço do Google. Antes de usar a credencial de armazenamento, você também deve conceder permissões à account serviço do Google para acessar seu bucket GCS específico.

1. Acesse o console do Google Cloud e abra o bucket GCS que você deseja acessar do Databricks.

   Para evitar cobranças de saída, o bucket deve estar na mesma região que o workspace Databricks do qual você deseja acessar os dados.

2. Na guia Permissão , clique em + Conceder acesso e atribua à conta de serviço as seguintes funções:

   • Leitor de bucket de armazenamento legado
   • Administrador de objetos de armazenamento

   Use o endereço de e-mail da conta de serviço como identificador principal.

3. Clique em Salvar .

Agora você pode criar um local externo que faça referência à sua credencial de armazenamento.

(Recomendado) Configurar permissões para eventos de arquivo

nota

Este passo é opcional, mas altamente recomendado. Se você não conceder acesso ao Databricks para configurar eventos de arquivo em seu nome, será necessário configurar eventos de arquivo manualmente para cada local. Caso contrário, você terá acesso limitado aos recursos críticos que Databricks pode lançar.

Os passos abaixo permitem que Databricks configure um pipeline de notificação completo para publicar mensagens de notificação de eventos dos seus buckets GCS no Google Cloud Pub/Sub. Eles presumem que você tem um projeto GCP com um bucket GCS e habilitou a API Pub/Sub.

1. Crie uma IAM role personalizada para eventos de arquivo.

   1. No console do Google Cloud do projeto que contém seu bucket GCS , navegue até IAM e Admin > Funções .

   2. Se você já tiver uma IAM role personalizada, selecione-a e clique em Editar função . Caso contrário, crie uma nova função clicando em + Criar função na página Funções .

   3. Na tela Criar função ou Editar função , adicione as seguintes permissões à sua IAM role e salve as alterações. Para obter instruções detalhadas, consulte a documentação do GCP.

      pubsub.subscriptions.consume
      pubsub.subscriptions.create
      pubsub.subscriptions.delete
      pubsub.subscriptions.get
      pubsub.subscriptions.list
      pubsub.subscriptions.update
      pubsub.topics.attachSubscription
      pubsub.topics.create
      pubsub.topics.delete
      pubsub.topics.get
      pubsub.topics.list
      pubsub.topics.update
      storage.buckets.update

2. Conceda acesso à função.

   1. Navegue até IAM e administrador > IAM .
   2. Clique em Conceder acesso .
   3. Insira sua account de serviço como principal.
   4. Selecione sua IAM role personalizada.
   5. Clique em Salvar .

3. Conceder permissões ao agente de serviço de armazenamento em nuvem

   1. Encontre o email account do agente de serviço seguindo estes passos na documentação do Google Cloud.
   2. No console do Google Cloud, navegue até IAM e Admin > IAM > Conceder acesso .
   3. Insira o email account do agente de serviço e atribua a função de Publicador do Pub/Sub* .

Agora você pode criar um local externo que faça referência a essa credencial de armazenamento.

Crie um local externo para um bucket do GCS

Esta seção descreve como criar um local externo usando o Catalog Explorer ou o SQL. Ele pressupõe que você já tenha uma credencial de armazenamento que permita acesso ao seu bucket do GCS. Se você não tiver uma credencial de armazenamento, siga os passos em Criar uma credencial de armazenamento que acesse GCS.

Opção 1: Criar um local externo manualmente usando o Catalog Explorer

Você pode criar um local externo manualmente usando o Catalog Explorer.

Para criar o local externo:

1. faça login em um workspace anexado ao metastore.

2. Na barra lateral, clique em Catálogo .

3. Na página Acesso rápido , clique no botão Dados externos > , vá para a tab Locais externos e clique em Criar local externo .

4. Digite um nome de local externo .

5. Em Tipo de armazenamento , selecione GCP .

6. Em URL , insira o caminho do bucket do GCS. Por exemplo, gs://mybucket/<path>.

7. Em Credencial de armazenamento , selecione a credencial de armazenamento que concede acesso ao local externo.

8. (Opcional) Se você quiser que os usuários tenham acesso somente leitura ao local externo, clique em Opções avançadas e selecione Limitar ao uso somente leitura . Para obter mais informações, consulte Marcar um local externo como somente leitura.

9. (Opcional) Se o local externo for destinado a um catálogo federado Hive metastore , clique em Opções avançadas e ative o modo de fallback .

   Consulte Habilitar modo de fallback em locais externos.

10. (Opcional) Para habilitar a capacidade de assinar notificações de alterações no local externo, clique em Opções avançadas e selecione Habilitar eventos de arquivo .

    Para obter detalhes, consulte (Recomendado) Habilitar eventos de arquivo para um local externo.

11. Clique em Criar .

12. (Opcional) Vincule o local externo ao espaço de trabalho específico.

    Por default, qualquer usuário privilegiado pode usar o local externo em qualquer workspace anexado ao metastore. Se você quiser permitir acesso somente de um espaço de trabalho específico, vá até a tab espaço de trabalho e atribua o espaço de trabalho. Consulte Atribuir um local externo a um espaço de trabalho específico.

13. Vá para a tab Permissões para conceder permissão para usar o local externo.

    Para que qualquer pessoa possa usar o local externo, você deve conceder permissões:

    • Para usar o local externo para adicionar um local de armazenamento de gerenciamento ao metastore, catálogo ou esquema, conceda o privilégio CREATE MANAGED LOCATION .
    • Para criar tabelas ou volumes externos, conceda CREATE EXTERNAL TABLE ou CREATE EXTERNAL VOLUME.
    1. Clique em Conceder .
    2. Na caixa de diálogo Conceder em <external location> , selecione usuários, grupos ou entidade de serviço no campo Principais e selecione o privilégio que deseja conceder.
    3. Clique em Conceder .

Opção 2: Criar um local externo usando SQL

Para criar um local externo usando SQL, execute o seguinte comando em um Notebook ou no editor de consultas SQL . Substitua os valores do espaço reservado. Para permissões e pré-requisitos necessários, consulte Requisitos.

• <location-name>: Um nome para o local externo. Se location_name incluir caracteres especiais, como hifens (-), ele deverá ser cercado por acentos graves ( ). Veja Nomes.
• <bucket-path>: o caminho em seu locatário de nuvem ao qual este local externo concede acesso. Por exemplo, gs://mybucket.
• <storage-credential-name>: O nome da credencial de armazenamento que autoriza a leitura e a gravação no bucket. Se o nome da credencial de armazenamento incluir caracteres especiais, como hifens (-), ele deverá ser cercado por acentos graves ( ).

SQL

CREATE EXTERNAL LOCATION [IF NOT EXISTS] `<location-name>`
URL '<bucket-path>'
WITH ([STORAGE] CREDENTIAL `<storage-credential-name>`)
[COMMENT '<comment-string>'];

Se você quiser limitar o acesso a locais externos a um espaço de trabalho específico em sua account, também conhecido como vinculação de workspace ou isolamento de local externo, consulte Atribuir um local externo a um espaço de trabalho específico.

Verifique a conexão

Para verificar se você criou o local externo com sucesso, tente ler um arquivo do local externo. Por exemplo, suponha que você tenha um local externo gs://external-location-bucket contendo um arquivo CSV chamado example.csv. Para ler o arquivo gs://external-location-bucket/example.csv , siga estes passos:

1. Na barra lateral, clique em Workspace .

2. Clique em Criar e selecione Notebook .

3. execute o seguinte trecho de código Python :

   Python

   display(dbutils.fs.ls('gs://external-location-bucket/'))

   Isso exibe uma lista de caminhos de arquivos no local externo. Neste exemplo, o arquivo gs://external-location-bucket/example.csv aparece na saída.

4. Para ler um arquivo específico no local externo, execute o seguinte trecho de código Python :

   Python

   spark.read.format("csv") \
      .option("header", "true") \
      .option("delimiter", ";") \
      .load('gs://external-location-bucket/example.csv') \
      .display()

   Isso exibe os dados no arquivo gs://external-location-bucket/example.csv .

Próximos passos

• Conceda permissão a outros usuários para usar locais externos. Veja gerenciar locais externos.
• Defina locais de armazenamento gerenciais usando locais externos. Consulte Especificar um local de armazenamento de gerenciamento no Unity Catalog.
• Defina tabelas externas usando locais externos. Veja Trabalhar com tabelas externas.
• Defina volumes externos usando locais externos. Veja O que são volumes Unity Catalog ?.