Catégories :

Utilisateur et sécurité DDL (Intégrations de services tiers)

CREATE API INTEGRATION

Crée un nouvel objet d’intégration API dans le compte ou remplace une intégration API existante.

Un objet d’intégration API stocke des informations sur un service proxy HTTPS, notamment des informations sur :

  • Le fournisseur de plate-forme Cloud (par exemple Amazon AWS).

  • Le type de service proxy (dans le cas où le fournisseur de plate-forme Cloud propose plusieurs types de service proxy).

  • L’identifiant et les informations d’identification d’accès pour un rôle de plate-forme Cloud disposant des privilèges suffisants pour utiliser le service proxy. Par exemple, sur AWS, le ARN (Amazon resource name) du rôle sert d’identifiant et d’informations d’identification d’accès.

    Lorsque cet utilisateur Cloud se voit accorder les privilèges appropriés, Snowflake peut utiliser cet utilisateur pour accéder aux ressources sur le service proxy (une instance du service proxy HTTPS natif de la plate-forme Cloud, par exemple, une instance Amazon AWS API Gateway).

  • Un objet d’intégration API spécifie également les points de terminaison et les ressources autorisés (et éventuellement bloqués) sur ces services proxy.

Voir aussi :

ALTER API INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , Fonctions externes , CREATE EXTERNAL FUNCTION

Dans ce chapitre :

Syntaxe

La syntaxe est différente pour chaque plate-forme Cloud.

Pour Amazon AWS API Gateway

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

Paramètres requis

Pour Amazon AWS API Gateway

nom_intégration

Spécifie le nom de l’intégration API. Ce nom suit les règles de Identificateurs d’objet. Le nom doit être unique parmi les intégrations API dans le schéma actuel.

info_fournisseur

Spécifie le type de service proxy HTTPS. Les valeurs valides sont :

  • aws_api_gateway: pour Amazon AWS API Gateway.

rôle_iam

Pour Amazon AWS, il s’agit du ARN (Amazon resource name) d’un rôle de plate-forme Cloud.

ENABLED = < TRUE | FALSE >

Spécifie si cette intégration API est activée ou désactivée. Si l’intégration API est désactivée, toute fonction externe qui en dépend ne fonctionnera pas.

La valeur est insensible à la casse.

La valeur par défaut est TRUE.

API_ALLOWED_PREFIXES = (...)

Limite explicitement les fonctions externes qui utilisent l’intégration pour référencer un ou plusieurs points de terminaison de service proxy HTTPS (par exemple, Amazon AWS API Gateway) et les ressources au sein de ces proxy. Prend en charge une liste d’URLs séparée par des virgules, qui sont traitées comme des préfixes (pour plus de détails, voir ci-dessous).

Chaque URL dans API_ALLOWED_PREFIXES = (...) est traitée comme un préfixe. Par exemple, si vous spécifiez :

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

cela signifie que toutes les ressources sous

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

sont autorisés. Par exemple, ce qui suit est autorisé :

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

Pour maximiser la sécurité, vous devez restreindre les emplacements autorisés aussi étroitement que possible.

Paramètres facultatifs

API_BLOCKED_PREFIXES = (...)

Répertorie les points de terminaison et les ressources du service proxy HTTPS pour lesquels l’appel à partir de Snowflake n’est pas autorisé.

Les valeurs possibles pour les emplacements suivent les mêmes règles que pour API_ALLOWED_PREFIXES ci-dessus.

API_BLOCKED_PREFIXES a priorité sur API_ALLOWED_PREFIXES. Si un préfixe correspond aux deux, il est bloqué. En d’autres termes, Snowflake autorise toutes les valeurs qui correspondent à API_ALLOWED_PREFIXES sauf les valeurs qui correspondent également à API_BLOCKED_PREFIXES.

Si une valeur est en dehors des API_ALLOWED_PREFIXES, vous n’avez pas besoin de la bloquer explicitement.

COMMENT = '<string_literal>'

Une description de la fonction externe.

Notes sur l’utilisation

  • Seuls les utilisateurs Snowflake qui ont le rôle ACCOUNTADMIN ou qui ont un rôle disposant du privilège global CREATE INTEGRATION peuvent exécuter CREATE API INTEGRATION.

  • Seuls les rôles Snowflake avec des privilèges OWNERSHIP ou USAGE sur l’intégration API peuvent utiliser directement l’intégration API, par exemple en créant une fonction externe qui spécifie cette intégration API.

  • Un objet d’intégration API est lié à un compte de plate-forme Cloud spécifique et à un rôle au sein de ce compte, mais pas à une URL de proxy HTTPS spécifique. Vous pouvez créer plusieurs instances d’un service proxy HTTPS dans un compte de fournisseur de Cloud et vous pouvez utiliser la même intégration API pour vous authentifier auprès de plusieurs services proxy dans ce compte.

  • Votre compte Snowflake peut avoir plusieurs objets d’intégration API, par exemple, pour différents comptes de plate-forme Cloud.

  • Plusieurs fonctions externes peuvent utiliser le même objet d’intégration API, et donc le même service proxy HTTPS.

  • Sur AWS, les fonctions externes nécessitent des points de terminaison régionaux. Pour plus de détails, voir Amazon AWS API Gateway.

Exemples

Cet exemple montre la création d’une intégration API et l’utilisation de cette intégration API dans une instruction CREATE EXTERNAL FUNCTION suivante :

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