CREATE STORAGE INTEGRATION¶

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>' ]

Onde:

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ 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_EXTERNAL_ID = 'external_id'

Especifica opcionalmente um ID externo que o Snowflake usa para estabelecer uma relação de confiança com AWS. Você deve especificar o mesmo ID externo na política de confiança da função IAM que você configurou para esta integração de armazenamento. Para obter mais informações, consulte Como usar um ID externo ao conceder acesso aos seus recursos do AWS a terceiros.

Se você não especificar um valor para esse parâmetro, o Snowflake gerará automaticamente um ID externo quando você criar a integração de armazenamento.

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:

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¶

• 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