CREATE STORAGE INTEGRATION

Cria uma nova integração de armazenamento na conta ou substitui uma integração existente.

Uma integração de armazenamento é um objeto Snowflake que armazena uma entidade gerada de gerenciamento de identidade e acesso (IAM) para seu armazenamento externo em nuvem, junto com um conjunto opcional de locais de armazenamento permitidos ou bloqueados (Amazon S3, Google Cloud Storage ou Microsoft Azure). Os administradores do provedor de nuvem em sua organização concedem permissões nos locais de armazenamento à entidade gerada. Esta opção permite aos usuários evitar fornecer credenciais ao criar estágios ou ao carregar ou descarregar dados.

Uma única integração de armazenamento pode oferecer suporte para múltiplos estágios externos. A URL na definição do estágio deve estar alinhada com o local de armazenamento especificado para o parâmetro STORAGE_ALLOWED_LOCATIONS.

Nota

  • As integrações de armazenamento podem ser configuradas para oferecer suporte ao armazenamento em nuvem Amazon S3, Google Cloud Storage ou Microsoft Azure, independentemente do provedor de nuvem que hospede sua conta Snowflake. Se seu armazenamento em nuvem estiver localizado em uma plataforma de nuvem diferente de sua conta Snowflake, o local de armazenamento deve estar na nuvem pública e não em um ambiente virtual privado.

    Os provedores de nuvem cobram pelos dados transferidos de sua própria rede. Para recuperar essas despesas, a Snowflake cobra uma taxa por byte quando você descarrega dados do Snowflake (hospedados no Amazon Web Services (AWS), Google Cloud Platform ou Microsoft Azure) para um estágio externo em uma região diferente ou em um provedor de nuvem diferente. A Snowflake não cobra pela entrada de dados (isto é, quando você carrega dados no Snowflake). Para obter mais detalhes, consulte a página de preços (no site da Snowflake).

  • Atualmente, o acesso ao armazenamento em nuvem em uma região governamental usando uma integração de armazenamento está limitado às contas Snowflake hospedadas na mesma região governamental. O acesso ao seu armazenamento em nuvem a partir de uma conta hospedada fora da região governamental utilizando credenciais diretas é suportado.

Consulte também:

ALTER STORAGE INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS

Sintaxe

CREATE [ OR REPLACE ] STORAGE INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = EXTERNAL_STAGE
  cloudProviderParams
  ENABLED = { TRUE | FALSE }
  STORAGE_ALLOWED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] )
  [ STORAGE_BLOCKED_LOCATIONS = ('<cloud>://<bucket>/<path>/' [ , '<cloud>://<bucket>/<path>/' ... ] ) ]
  [ COMMENT = '<string_literal>' ]
Copy

Onde:

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  [ STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control' ]
Copy
cloudProviderParams (for Google Cloud Storage) ::=
  STORAGE_PROVIDER = 'GCS'
Copy
cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'
Copy

Parâmetros obrigatórios

name

Cadeia de caracteres que especifica o identificador (ou seja, nome) para a integração; deve ser única em sua conta.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

TYPE = EXTERNAL_STAGE

Especifique o tipo de integração:

  • EXTERNAL_STAGE: cria uma interface entre o Snowflake e um local externo de armazenamento em nuvem.

ENABLED = TRUE | FALSE

Especifica se esta integração de armazenamento está disponível para uso em estágios.

  • TRUE permite que os usuários criem novos estágios que fazem referência a esta integração. Os estágios existentes que fazem referência a esta função de integração normalmente.

  • FALSE impede que os usuários criem novos estágios que referenciem esta integração. Os estágios existentes que fazem referência a esta integração não podem acessar o local de armazenamento na definição do estágio.

STORAGE_ALLOWED_LOCATIONS = ('cloud_specific_url')

Limita explicitamente os estágios externos que utilizam a integração para referenciar um ou mais locais de armazenamento (como bucket S3, bucket GCS ou contêiner Azure). Oferece suporte a uma lista separada por vírgula de URLs para buckets existentes e, opcionalmente, caminhos usados para armazenar arquivos de dados para carregamento/descarregamento. Como alternativa, oferece suporte ao curinga *, que significa “permitir o acesso a todos os buckets e/ou caminhos”.

Observe que se o valor STORAGE_ALLOWED_LOCATIONS incluir um local de armazenamento específico, todos os subcaminhos no mesmo local deverão ser permitidos. Nenhum subcaminho pode ser incluído em um valor STORAGE_BLOCKED_LOCATIONS. Por exemplo, se STORAGE_ALLOWED_LOCATIONS inclui storage_location/, então STORAGE_BLOCKED_LOCATIONS não pode incluir storage_location/path1/. Da mesma forma, se STORAGE_ALLOWED_LOCATIONS inclui storage_location/path1/, então STORAGE_BLOCKED_LOCATIONS não pode incluir storage_location/path1/path2/, e assim por diante.

Amazon S3

STORAGE_ALLOWED_LOCATIONS = ( 's3://bucket/path/' [ , 's3://bucket/path/' ... ] ) | STORAGE_ALLOWED_LOCATIONS = ( 's3gov://bucket/path/' [ , 's3gov://bucket/path/' ... ] )

  • O prefixo s3 refere-se ao armazenamento S3 em regiões públicas do AWS.

    O prefixo s3gov refere-se ao armazenamento S3 em regiões governamentais.

  • bucket é o nome de um bucket S3 que armazena seus arquivos de dados (por exemplo, mybucket).

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o acesso a um conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Google Cloud Storage

STORAGE_ALLOWED_LOCATIONS = ( 'gcs://bucket/path/' [ , 'gcs://bucket/path/' ... ] )

  • bucket é o nome de um bucket GCS que armazena seus arquivos de dados (por exemplo, mybucket).

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o acesso a um conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Microsoft Azure

STORAGE_ALLOWED_LOCATIONS = ( 'azure://account.blob.core.windows.net/container/path/' [ , 'azure://account.blob.core.windows.net/container/path/' ... ] )

  • account é o nome da conta de armazenamento Azure (por exemplo, myaccount). Use o ponto de extremidade blob.core.windows.net para todos os tipos com suporte de contas de armazenamento de blobs Azure, incluindo Data Lake Storage Gen2.

  • container é o nome de um contêiner de armazenamento de blobs do Azure que armazena seus arquivos de dados (por exemplo, mycontainer).

  • path é um caminho opcional que distingue letras maiúsculas de minúsculas para arquivos no local de armazenamento em nuvem (ou seja, os arquivos têm nomes que começam com uma cadeia de caracteres comum) que limita o acesso a um conjunto de arquivos. Os caminhos são chamados alternativamente de prefixos ou pastas por diferentes serviços de armazenamento em nuvem.

Parâmetros opcionais

STORAGE_BLOCKED_LOCATIONS = ('cloud_specific_url')

Proíbe explicitamente os estágios externos que utilizam a integração de referenciar um ou mais locais de armazenamento (ou seja, buckets S3 ou buckets GCS). Oferece suporte a uma lista separada por vírgula de URLs para locais de armazenamento existentes e, opcionalmente, caminhos usados para armazenar arquivos de dados para carregamento/descarregamento. Comumente usado quando STORAGE_ALLOWED_LOCATIONS é definido como o curinga *, permitindo acesso a todos os buckets em sua conta exceto para locais de armazenamento bloqueados e, opcionalmente, caminhos.

Nota

Certifique-se de incluir somente URLs de local individual de armazenamento em nuvem entre aspas. Se você incluir o valor inteiro STORAGE_BLOCKED_LOCATIONS entre aspas, o valor será inválido. Como resultado, a configuração do parâmetro STORAGE_BLOCKED_LOCATIONS é ignorada quando usuários criam estágios que fazem referência à integração de armazenamento.

Amazon S3

STORAGE_BLOCKED_LOCATIONS = ( 's3://bucket/path/' [ , 's3://bucket/path/' ... ] ) | STORAGE_ALLOWED_LOCATIONS = ( 's3gov://bucket/path/' [ , 's3gov://bucket/path/' ... ] )

  • O prefixo s3 refere-se ao armazenamento S3 em regiões públicas do AWS.

    O prefixo s3gov refere-se ao armazenamento S3 em regiões governamentais.

  • bucket é o nome de um bucket S3 que armazena seus arquivos de dados (por exemplo, mybucket).

  • path é um caminho opcional (ou diretório) no bucket que limita ainda mais o acesso aos arquivos de dados.

Google Cloud Storage

STORAGE_BLOCKED_LOCATIONS = ( 'gcs://bucket/path/' [ , 'gcs://bucket/path/' ... ] )

  • bucket é o nome de um bucket GCS que armazena seus arquivos de dados (por exemplo, mybucket).

  • path é um caminho opcional (ou diretório) no bucket que limita ainda mais o acesso aos arquivos de dados.

Microsoft Azure

STORAGE_BLOCKED_LOCATIONS = ( 'azure://account.blob.core.windows.net/container/path/' [ , 'azure://account.blob.core.windows.net/container/path/' ... ] )

  • account é o nome da conta de armazenamento Azure (por exemplo, myaccount).

  • container é o nome de um contêiner de armazenamento de blobs do Azure que armazena seus arquivos de dados (por exemplo, mycontainer).

  • path é um caminho opcional (ou diretório) no bucket que limita ainda mais o acesso aos arquivos de dados.

COMMENT = 'string_literal'

Cadeia de caracteres (literal) que especifica um comentário da integração.

Padrão: sem valor

Parâmetros do provedor de nuvem (cloudProviderParams)

Amazon S3

STORAGE_PROVIDER = { S3 | S3GOV }

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados:

  • S3: armazenamento S3 em regiões públicas do AWS.

  • S3GOV: armazenamento S3 em regiões governamentais do AWS.

STORAGE_AWS_ROLE_ARN = iam_role

Especifica o Amazon Resource Name (ARN) da função AWS de gerenciamento de identidade e acesso (IAM) que concede privilégios no bucket S3 que contém seus arquivos de dados. Para obter mais informações, consulte Configuração de acesso seguro ao Amazon S3.

STORAGE_AWS_OBJECT_ACL = 'bucket-owner-full-control'

Habilita o suporte de listas de controle de acesso (ACLs) da AWS para conceder total controle ao proprietário do bucket. Os arquivos criados nos buckets S3 da Amazon a partir de dados de tabela descarregados são de propriedade de uma função de Gerenciamento de Identidade e Acesso (IAM) do AWS. ACLs oferecem suporte ao caso de uso em que funções IAM em uma conta AWS são configuradas para acessar buckets S3 em uma ou mais outras contas AWS. Sem suporte para ACL, os usuários nas contas do proprietário do bucket não poderiam acessar os arquivos de dados descarregados para um estágio externo (S3) utilizando uma integração de armazenamento.

Quando os usuários descarregam os dados da tabela Snowflake para arquivos de dados em um estágio S3 usando COPY INTO <local>, a operação de descarregamento aplica uma ACL aos arquivos de dados descarregados. Os arquivos de dados aplicam o privilégio "s3:x-amz-acl":"bucket-owner-full-control" aos arquivos, concedendo ao proprietário do bucket S3 total controle sobre eles.

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados.

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados.

AZURE_TENANT_ID = 'tenant_id'

Especifica a ID de seu locatário do Office 365 ao qual pertencem as contas de armazenamento permitidas e bloqueadas. Uma integração de armazenamento pode autenticar a somente um locatário e, portanto, os locais de armazenamento permitidos e bloqueados devem se referir às contas de armazenamento que pertencem a este locatário.

Para encontrar sua ID de locatário, entre no portal Azure e clique em Azure Active Directory » Properties. A ID do locatário é exibida no campo Tenant ID.

Requisitos de controle de acesso

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio

Objeto

Notas

CREATE INTEGRATION

Conta

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso

Cuidado

Recriar uma integração de armazenamento (usando CREATE OR REPLACE STORAGE INTEGRATION) quebra a associação entre a integração de armazenamento e qualquer estágio que a referencie. Isso porque um estágio se liga a uma integração de armazenamento usando uma ID oculta em vez do nome da integração de armazenamento. Nos bastidores, a sintaxe CREATE OR REPLACE descarta o objeto e o recria com uma ID oculta diferente.

Se você precisar recriar uma integração de armazenamento após ter sido vinculada a um ou mais estágios, será necessário restabelecer a associação entre cada estágio e a integração de armazenamento executando ALTER STAGE stage_name SET STORAGE_INTEGRATION = storage_integration_name, em que:

  • stage_name é o nome do estágio.

  • storage_integration_name é o nome da integração de armazenamento.

  • Em relação aos metadados:

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

  • Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

Exemplos

O exemplo a seguir cria uma integração que limita explicitamente os estágios externos que utilizam a integração para referenciar um de dois buckets ou caminhos:

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('s3://mybucket1/path1/', 's3://mybucket2/path2/');
Copy

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('gcs://mybucket1/path1/', 'gcs://mybucket2/path2/');
Copy

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_ALLOWED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path1/', 'azure://myaccount.blob.core.windows.net/mycontainer/path2/');
Copy

O exemplo a seguir cria uma integração que permite que estágios externos que utilizam a integração façam referência a qualquer bucket e caminho em sua conta, exceto aqueles que estão explicitamente bloqueados:

Amazon S3

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket3/path3/', 's3://mybucket4/path4/');
Copy

Google Cloud Storage

CREATE STORAGE INTEGRATION gcs_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('gcs://mybucket3/path3/', 'gcs://mybucket4/path4/');
Copy

Microsoft Azure

CREATE STORAGE INTEGRATION azure_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'AZURE'
  ENABLED = TRUE
  AZURE_TENANT_ID = 'a123b4c5-1234-123a-a12b-1a23b45678c9'
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('azure://myaccount.blob.core.windows.net/mycontainer/path3/', 'azure://myaccount.blob.core.windows.net/mycontainer/path4/');
Copy