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 ce qui suit :

Fournisseur de plateforme cloud (tel qu’Amazon AWS).

Référentiel Git

Type de service proxy (dans le cas où le fournisseur de plateforme Cloud propose plusieurs types de service proxy).

Identifiants et informations d’identification d’accès du service externe disposant de privilèges suffisants pour utiliser le service. Par exemple, sur AWS, l’ARN (Amazon Resource Name) du rôle sert d’identificateur et d’identifiants d’accès.

Lorsque cet utilisateur dispose des privilèges appropriés, Snowflake peut l’utiliser pour accéder aux ressources. Par exemple, il peut s’agir d’une instance du service proxy HTTPS natif de la plateforme cloud, par exemple une instance d’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 API externe.

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.

Pour référentiel 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

Notez que git_https_api 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.

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

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.

API_AWS_ROLE_ARN = iam_role

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

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.

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.

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.

API_PROVIDER = azure_api_management

Spécifie que cette intégration est utilisée avec les services Azure API Management. N’utilisez pas de guillemets autour de azure_api_management.

AZURE_TENANT_ID = 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_AD_APPLICATION_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_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.

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.

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.

API_PROVIDER = google_api_gateway

Spécifie que cette intégration est utilisée avec Google Cloud. La seule valeur valide à cet effet est google_api_gateway. La valeur ne doit pas être entre guillemets.

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

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.

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.

Pour référentiel Git¶

Pour un exemple, voir Créer une API d’intégration pour interagir avec l’API du référentiel.

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.

API_PROVIDER = git_https_api

Spécifie que cette intégration est utilisée avec CREATE GIT REPOSITORY pour créer une intégration avec un référentiel Git. La seule valeur valide à cet effet est git_https_api. La valeur ne doit pas être entre guillemets.

API_ALLOWED_PREFIXES = (...)

Limite explicitement les fonctions qui utilisent l’intégration pour référencer un ou plusieurs points de terminaison de service proxy HTTPS 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.

Snowflake prend en charge les URLs suivantes :

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

https://github.com/my-account

cela signifie que toutes les ressources sous

https://github.com/my-account

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

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

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

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, le référentiel Git ne sera pas accessible.

La valeur est insensible à la casse.

La valeur par défaut est TRUE.

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.

API_KEY = api_key

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

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

Spécifie les secrets que l’UDF ou le code du gestionnaire de procédure peut utiliser lors de l’accès au référentiel Git à la valeur API_ALLOWED_PREFIXES. Vous spécifiez un secret de cette liste lors de la spécification des identifiants Git avec le paramètre GIT_CREDENTIALS.

La valeur de ce paramètre doit être l’une des suivantes :

Un ou plusieurs noms entièrement qualifiés de secret Snowflake pour autoriser n’importe lequel des secrets de la liste.
(Par défaut) all pour autoriser tout secret.
none pour n’autoriser aucun secret.

Le paramètre ALLOWED_API_AUTHENTICATION_INTEGRATIONS peut également spécifier des secrets autorisés. Pour plus d’informations, voir Notes sur l’utilisation.

Pour des informations de référence sur les secrets, voir CREATE SECRET.

COMMENT = 'string_literal'

Description de l’intégration.

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¶

Amazon API Gateway¶

L’exemple suivant 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

Référentiel Git¶

Pour un exemple d’intégration API utilisée pour intégrer un référentiel Git, voir Créer une API d’intégration pour interagir avec l’API du référentiel.