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 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 API Gateway

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = { aws_api_gateway | aws_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>' ]
    ;

Notez que ni aws_api_gateway ni aws_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>' ]
    ;

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

Notez que google_api_gateway ne doit pas être entre guillemets.

Paramètres requis

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

info_fournisseur

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.

rôle_iam

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

api_key

The API key (also called a « subscription key »).

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

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

id_client

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

id_application_azure

« 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 de l” « ID de l’application AD de l’application de la fonction Azure » que vous avez enregistré dans la feuille de calcul dans ces instructions.

api_key

The API key (also called a « subscription key »).

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

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

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.

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