CREATE API INTEGRATION¶

Cria um novo objeto de integração de API na conta, ou substitui uma integração de API existente.

Um objeto de integração de API armazena informações sobre um serviço de proxy HTTPS, incluindo informações sobre o seguinte:

Um provedor de plataforma de nuvem (como AWS).

Um repositório Git.

O tipo de serviço de proxy (como quando um provedor de plataforma de nuvem oferece mais de um tipo de serviço de proxy).

O identificador e as credenciais de acesso para o serviço externo que tem privilégios suficientes para usar o serviço. Por exemplo, em AWS, o ARN (nome do recurso Amazon) da função serve como identificador e credenciais de acesso.

Quando esse usuário recebe privilégios apropriados, o Snowflake pode usá-lo para acessar recursos. Por exemplo, pode ser uma instância do serviço de proxy HTTPS nativo da plataforma de nuvem, por exemplo, uma instância de um Amazon API Gateway.

Um objeto de integração de API também especifica os pontos de extremidade e recursos permitidos (e opcionalmente bloqueados) nesses serviços de proxy.

Consulte também:: ALTER API INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , Como escrever funções externas , CREATE EXTERNAL FUNCTION

Sintaxe¶

A sintaxe é diferente para cada API de arquivo externo.

Para Amazon API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }
  API_AWS_ROLE_ARN = '<iam_role>'
  [ API_KEY = '<api_key>' ]
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Note que aws_api_gateway ou aws_private_api_gateway ou aws_gov_api_gateway ou aws_gov_private_api_gateway não deve estar entre aspas.

Para Azure API Management¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = azure_api_management
  AZURE_TENANT_ID = '<tenant_id>'
  AZURE_AD_APPLICATION_ID = '<azure_application_id>'
  [ API_KEY = '<api_key>' ]
  API_ALLOWED_PREFIXES = ( '<...>' )
  [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Note que azure_api_management não deve estar entre aspas.

Para Google Cloud API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = google_api_gateway
  GOOGLE_AUDIENCE = '<google_audience_claim>'
  API_ALLOWED_PREFIXES = ( '<...>' )
  [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Note que google_api_gateway não deve estar entre aspas.

Para repositório Git¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name> [, <secret_name>, ... ] | all | none } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

Note que git_https_api não deve estar entre aspas.

Parâmetros obrigatórios¶

Para Amazon API Gateway¶

integration_name

Especifica o nome da integração de API. Este nome segue as regras para Identificadores de objetos. O nome deve ser único entre as integrações de API em sua conta.

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

Especifica o tipo de serviço de proxy HTTPS. Os valores válidos são:

aws_api_gateway: para Amazon API Gateway usando pontos de extremidade regionais.

aws_private_api_gateway: para Amazon API Gateway usando pontos de extremidade privados.

aws_gov_api_gateway: para Amazon API Gateway usando pontos de extremidade GovCloud do governo dos EUA.

aws_gov_private_api_gateway: para Amazon API Gateway usando pontos de extremidade GovCloud do governo dos EUA que também são pontos de extremidade privados.

API_AWS_ROLE_ARN = iam_role

Para Amazon AWS, este é o ARN (nome do recurso Amazon) de uma função da plataforma de nuvem.

API_ALLOWED_PREFIXES = (...)

Limita explicitamente as funções externas que utilizam a integração para referenciar um ou mais pontos de extremidade do servidor de proxy HTTPS (por exemplo, Amazon API Gateway) e recursos dentro desses proxies. Oferece suporte a uma lista de URLs separada por vírgulas, que são tratados como prefixos (para detalhes, consulte abaixo).

Cada URL em API_ALLOWED_PREFIXES = (...) é tratado como um prefixo. Por exemplo, se você especificar:

https://xyz.amazonaws.com/production/

isso significa que todos os recursos em

https://xyz.amazonaws.com/production/

são permitidos. Por exemplo, é permitido o seguinte:

https://xyz.amazonaws.com/production/ml1

Para maximizar a segurança, você deve restringir os locais permitidos de maneira mais precisa e prática possível.

ENABLED = { TRUE | FALSE }

Especifica se esta integração de API está habilitada ou desabilitada. Se a integração de API estiver desativada, qualquer função externa que conte com ela não funcionará.

O valor não diferencia maiúsculas e minúsculas.

O padrão é TRUE.

Para Azure API Management Service¶

integration_name

Especifica o nome da integração de API. Este nome segue as regras para Identificadores de objetos. O nome deve ser único entre as integrações de API em sua conta.

API_PROVIDER = azure_api_management

Especifica que esta integração é usada com os serviços do Azure API Management. Não coloque azure_api_management entre aspas.

AZURE_TENANT_ID = tenant_id

Especifica a ID de seu locatário do Office 365 ao qual pertencem todas as instâncias do Azure API Management. Uma integração de API pode autenticar apenas a um locatário, com isso os locais permitidos e bloqueados devem referir-se às instâncias do API Management 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.

AZURE_AD_APPLICATION_ID = azure_application_id

A “ID do aplicativo (cliente)” do aplicativo Azure AD (Active Directory) para seu serviço remoto. Se você seguiu as instruções em Criação de funções externas no Microsoft Azure, então este é o Azure Function App AD Application ID que você registrou na planilha naquelas instruções.

API_ALLOWED_PREFIXES = (...)

Limita explicitamente as funções externas que utilizam a integração para referenciar um ou mais pontos de extremidade do serviço de proxy HTTPS (por exemplo, serviços do Azure API Management) e recursos dentro desses proxies. Oferece suporte a uma lista de URLs separada por vírgulas, que são tratados como prefixos (para detalhes, consulte abaixo).

Cada URL em API_ALLOWED_PREFIXES = (...) é tratado como um prefixo. Por exemplo, se você especificar:

https://my-external-function-demo.azure-api.net/my-function-app-name

isso significa que todos os recursos em

https://my-external-function-demo.azure-api.net/my-function-app-name

são permitidos. Por exemplo, é permitido o seguinte:

https://my-external-function-demo.azure-api.net/my-function-app-name/my-http-trigger-function

Para maximizar a segurança, você deve restringir os locais permitidos de maneira mais precisa e prática possível.

ENABLED = { TRUE | FALSE }

Especifica se esta integração de API está habilitada ou desabilitada. Se a integração de API estiver desativada, qualquer função externa que conte com ela não funcionará.

O valor não diferencia maiúsculas e minúsculas.

O padrão é TRUE.

Para Google Cloud API Gateway¶

integration_name

Especifica o nome da integração de API. Este nome segue as regras para Identificadores de objetos. O nome deve ser único entre as integrações de API em sua conta.

API_PROVIDER = google_api_gateway

Especifica que esta integração é usada com o Google Cloud. O único valor válido para esta finalidade é google_api_gateway. O valor não deve estar entre aspas.

GOOGLE_AUDIENCE = google_audience

Isto é usado como reivindicação da audiência ao gerar o JWT (JSON Web Token) para autenticar no Google API Gateway. Para obter mais informações sobre autenticação com o Google, consulte a documentação de autenticação da conta de serviço do Google.

API_ALLOWED_PREFIXES = (...)

Limita explicitamente as funções externas que utilizam a integração para referenciar um ou mais pontos de extremidade do serviço de proxy HTTPS (por exemplo, Google Cloud API Gateways) e recursos dentro desses proxies. Oferece suporte a uma lista de URLs separada por vírgulas, que são tratados como prefixos (para detalhes, consulte abaixo).

Cada URL em API_ALLOWED_PREFIXES = (...) é tratado como um prefixo. Por exemplo, se você especificar:

https://my-external-function-demo.uc.gateway.dev/x

isso significa que todos os recursos em

https://my-external-function-demo.uc.gateway.dev/x

são permitidos. Por exemplo, é permitido o seguinte:

https://my-external-function-demo.uc.gateway.dev/x/y

Para maximizar a segurança, você deve restringir os locais permitidos de maneira mais precisa e prática possível.

ENABLED = { TRUE | FALSE }

Especifica se esta integração de API está habilitada ou desabilitada. Se a integração de API estiver desativada, qualquer função externa que conte com ela não funcionará.

O valor não diferencia maiúsculas e minúsculas.

O padrão é TRUE.

Para repositório Git¶

Para obter um exemplo, consulte Criação de uma integração da API para interagir com a API do repositório.

integration_name

Especifica o nome da integração de API. Este nome segue as regras para Identificadores de objetos. O nome deve ser único entre as integrações de API em sua conta.

API_PROVIDER = git_https_api

Especifica que esta integração é usada com CREATE GIT REPOSITORY para criar uma integração com um repositório Git. O único valor válido para esta finalidade é git_https_api. O valor não deve estar entre aspas.

API_ALLOWED_PREFIXES = (...)

Limita explicitamente funções que usam a integração para referenciar um ou mais pontos de extremidade do servidor proxy HTTPS e recursos dentro desses proxies. Suporta uma lista separada por vírgulas de URLs, que são tratadas como prefixos.

O Snowflake oferece suporte usando as seguintes URLs:

Cada URL em API_ALLOWED_PREFIXES = (...) é tratado como um prefixo. Por exemplo, se você especificar:

https://github.com/my-account

isso significa que todos os recursos em

https://github.com/my-account

são permitidos. Por exemplo, é permitido o seguinte:

https://github.com/my-account/myproject

Para maximizar a segurança, você deve restringir os locais permitidos de maneira mais precisa e prática possível.

ENABLED = { TRUE | FALSE }

Especifica se esta integração de API está habilitada ou desabilitada. Se a integração da API estiver desabilitada, o repositório Git não estará acessível.

O valor não diferencia maiúsculas e minúsculas.

O padrão é TRUE.

Parâmetros opcionais¶

API_BLOCKED_PREFIXES = (...)

Lista os pontos de extremidade e recursos no serviço de proxy HTTPS que não podem ser chamados do Snowflake.

Os valores possíveis para locais seguem as mesmas regras de API_ALLOWED_PREFIXES acima.

API_BLOCKED_PREFIXES tem precedência sobre API_ALLOWED_PREFIXES. Se um prefixo corresponder a ambos, então ele é bloqueado. Em outras palavras, o Snowflake permite todos os valores que correspondem a API_ALLOWED_PREFIXES exceto valores que também correspondem a API_BLOCKED_PREFIXES.

Se um valor estiver fora de API_ALLOWED_PREFIXES, você não precisa bloqueá-lo explicitamente.

API_KEY = api_key

A chave API (também chamada de «chave de assinatura»).

ALLOWED_AUTHENTICATION_SECRETS = ( secret_name [, secret_name ... ] | all | none )

Especifica os segredos que a UDF ou o código do manipulador de procedimento pode usar ao acessar o repositório Git no valor API_ALLOWED_PREFIXES. Você especifica um segredo desta lista ao especificar as credenciais Git com o parâmetro GIT_CREDENTIALS.

O valor desse parâmetro deve ser um dos seguintes:

Um ou mais nomes secretos Snowflake totalmente qualificados para permitir qualquer um dos segredos listados.
(Padrão) all para permitir qualquer segredo.
none para não permitir segredos.

O parâmetro ALLOWED_API_AUTHENTICATION_INTEGRATIONS também pode especificar segredos permitidos. Para obter mais informações, consulte Notas de uso.

Para obter informações de referência sobre segredos, consulte CREATE SECRET.

COMMENT = 'string_literal'

Uma descrição da integração.

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¶

Somente as funções do Snowflake com privilégios OWNERSHIP ou USAGE na integração de API podem usar a integração de API diretamente (por exemplo, criando uma função externa que especifica aquela integração de API).
Um objeto de integração de API está vinculado a uma conta e função específica da plataforma de nuvem dentro dessa conta, mas não a um URL do proxy HTTPS específico. Você pode criar mais de uma instância de um serviço de proxy HTTPS em uma conta de provedor de nuvem, e você pode usar a mesma integração de API para autenticar a vários serviços de proxy nessa conta.
Sua conta Snowflake pode ter múltiplos objetos de integração de API, por exemplo, para diferentes contas de plataformas de nuvem.
Várias funções externas podem usar o mesmo objeto de integração de API, e portanto o mesmo serviço de proxy HTTPS.
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¶

Amazon API Gateway¶

O exemplo a seguir mostra a criação de uma integração de API e o uso dessa integração de API em uma instrução CREATE EXTERNAL FUNCTION subsequente:

CREATE OR REPLACE API INTEGRATION demonstration_external_api_integration_01
  API_PROVIDER = aws_api_gateway
  API_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my_cloud_account_role'
  API_ALLOWED_PREFIXES = ('https://xyz.execute-api.us-west-2.amazonaws.com/production')
  ENABLED = TRUE;

CREATE OR REPLACE EXTERNAL FUNCTION local_echo(string_col VARCHAR)
  RETURNS VARIANT
  API_INTEGRATION = demonstration_external_api_integration_01
  AS 'https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo';

Copy

Repositório Git¶

Para um exemplo de integração de API usada para integrar um repositório Git, consulte Criação de uma integração da API para interagir com a API do repositório.