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 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 , Écriture de fonctions externes , CREATE EXTERNAL FUNCTION

Syntaxe¶

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

Pour 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

Notez que ni aws_api_gateway ni aws_private_api_gateway ni aws_gov_api_gateway ni aws_gov_private_api_gateway ne doivent être entre guillemets.

Pour 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

Notez que azure_api_management ne doit pas être entre guillemets.

Pour 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

Notez que google_api_gateway ne doit pas être entre guillemets.

Paramètres requis¶

Pour Amazon API Gateway¶

integration_name

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 de votre compte.

provider_info

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

aws_api_gateway: pour Amazon API Gateway utilisant des points de terminaison régionaux.

aws_private_api_gateway: pour Amazon API Gateway utilisant des points de terminaison privés.

aws_gov_api_gateway : pour Amazon API Gateway utilisant des points de terminaison GovCloud du gouvernement américain.

aws_gov_private_api_gateway : pour Amazon API Gateway utilisant des points de terminaison GovCloud du gouvernement américain qui sont également des points de terminaison privés.

iam_role

Pour Amazon AWS, il s’agit de l’ARN (Amazon Resource Name) d’un rôle de plate-forme Cloud.

api_key

La clé API (également appelée « clé d’abonnement »).

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 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.

Pour Azure API Management Service¶

integration_name

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 de votre compte.

tenant_id

Spécifie l” ID de votre client Office 365 auquel appartiennent toutes les instances Azure API Management. Une intégration API peut s’authentifier auprès d’un seul client. Les emplacements de stockage autorisés et bloqués doivent donc faire référence aux instances API Management qui appartiennent toutes à ce client.

Pour trouver votre ID de client, connectez-vous au portail Azure et cliquez sur Azure Active Directory » Properties. L” ID de client s’affiche dans le champ Tenant ID.

azure_application_id

« ID (client) de l’application » de l’application Azure AD (Active Directory) pour votre service à distance. Si vous avez suivi les instructions de Création de fonctions externes sur Microsoft Azure, alors il s’agit du Azure Function App AD Application ID que vous avez enregistré dans la feuille de calcul dans ces instructions.

api_key

La clé API (également appelée « clé d’abonnement »).

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, services Azure API Management) 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://my-external-function-demo.azure-api.net/my-function-app-name

cela signifie que toutes les ressources sous

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

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

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

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

Pour Google Cloud API Gateway¶

integration_name

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 de votre compte.

google_audience

Ceci est utilisé comme revendication d’audience lors de la génération du JWT (jeton Web JSON) pour s’authentifier auprès de la Google API Gateway. Pour plus d’informations sur l’authentification avec Google, veuillez consulter la documentation sur l’authentification du compte de service Google.

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, Google Cloud API Gateways) 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://my-external-function-demo.uc.gateway.dev/x

cela signifie que toutes les ressources sous

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

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

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

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

Paramètres facultatifs¶

Ces paramètres facultatifs s’appliquent à chacun des éléments suivants :

Amazon API Gateway.
Azure API Management Service.
Google Cloud API Gateway.

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.

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège	Objet	Remarques
CREATE INTEGRATION	Compte	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

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.
Concernant les métadonnées :

Attention

Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.
Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

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

Copy