Demander des intégrations d’accès externe (EAIs) avec des spécifications d’application¶

Accès à des points de terminaison externes à partir d’une application¶

Pour accéder à un point de terminaison externe, une application doit créer une règle de réseau et une intégration d’accès externe. Une intégration d’accès externe utilise des règles de réseau pour restreindre l’accès à des emplacements de réseau externes spécifiques. Les règles de réseau définissent les points de terminaison externes auxquels une application peut accéder.

Pour configurer une application pour qu’elle utilise une intégration d’accès externe, procédez comme suit :

• Utilisez l’octroi automatique de privilèges pour demander des privilèges au consommateur pour créer une intégration d’accès externe.

• Ajoutez une intégration d’accès externe à une application.

• Utilisez les spécifications d’application pour demander des autorisations au consommateur pour se connecter à un point de terminaison externe.

Workflow de la spécification d’application pour les intégrations d’accès externe¶

Le workflow général de configuration d’une application pour utiliser une intégration d’accès externe est le suivant :

1. Les fournisseurs configurent l’octroi automatique de privilèges pour l’application. Cela permet aux consommateurs de donner l’autorisation à une application de créer l’intégration d’accès externe.

   Note

   Les spécifications d’application exigent que manifest_version = 2 soit défini dans le fichier manifeste.

2. Les fournisseurs ajoutent le privilège CREATE EXTERNAL ACCESSINTEGRATION au fichier manifeste.

3. Les fournisseurs ajoutent les instructions SQL au script d’installation pour créer les objets suivants en fonction des besoins :

   • Règle de réseau

   • Intégration d’accès externe

   • Spécification d’application

   Le script d’installation crée la spécification d’application et les autres objets lors de l’installation ou de la mise à niveau de l’application, ou lors de son exécution.

4. Lors de la configuration de l’application, les consommateurs approuvent les ports hôtes et les autres services externes. Pour plus d’informations sur la façon dont les consommateurs visualisent et approuvent les spécifications d’application, consultez Approuver des connexions à des ressources externes à l’aide de spécifications d’application.

Définition de la spécification d’application pour les intégrations d’accès externes¶

Pour une intégration d’accès externe, la définition de la spécification d’application contient les entrées suivantes :

• HOST_PORTS : Liste des ports hôtes définis dans la règle de réseau dont l’application a besoin.

• PRIVATE_HOST_PORTS : Liste des ports hôtes privés qui permettent une connexion privée à des ressources externes à Snowflake.

Spécifier la version du fichier manifeste¶

Pour activer l’octroi automatique de privilèges pour une application, définissez la version au début du fichier manifeste, comme indiqué dans l’exemple suivant :

manifest_version: 2

Ajoutez le privilège CREATE EXTERNAL ACCESS INTEGRATION au fichier manifeste.¶

Le privilège CREATE EXTERNAL ACCESS INTEGRATION permet à l’application de créer une intégration d’accès externe lors de l’installation ou de la mise à niveau. Pour configurer une application afin qu’elle demande le privilège CREATE EXTERNAL ACCESS INTEGRATION, ajoutez le code suivant à la section privileges du fichier manifeste :

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...

Grâce à manifest_version: 2, lorsque l’application est installée ou mise à niveau, Snowflake accorde automatiquement le privilège CREATE EXTERNAL ACCESS INTEGRATION sur l’application.

Ajouter une règle de réseau et une intégration d’accès externe au script d’installation¶

Les intégrations d’accès externes sont les objets Snowflake qui permettent d’accéder à des emplacements de réseau externes spécifiques. Les intégrations d’accès externes contiennent une liste de règles de réseau qui spécifient les emplacements externes auxquels une application peut accéder.

Pour créer une règle de réseau pour une application, ajoutez la commande CREATE NETWORK RULE au script d’installation comme indiqué dans l’exemple suivant :

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
 TYPE = HOST_PORT
 VALUE_LIST = ( 'example.com' )
 MODE = EGRESS;

Les propriétés HOST_PORT et VALUE_LIST indiquent que la règle de réseau doit pointer vers un domaine, un port ou une plage de ports valide. Lorsqu’une application est installée ou mise à niveau, un consommateur accorde l’autorisation à l’application d’utiliser ces domaines ou ports.

Créer une intégration d’accès externe¶

Pour créer une intégration d’accès externe pour une application, ajoutez la commande CREATE EXTERNAL ACCESS INTEGRATION au script d’installation comme indiqué dans l’exemple suivant :

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;

Créer une fonction définie par l’utilisateur pour accéder au point de terminaison externe¶

Après avoir créé l’intégration d’accès externe, le script d’installation peut créer des fonctions définies par l’utilisateur et des procédures stockées qui l’utilisent pour se connecter aux points de terminaison définis dans la règle de réseau.

L’exemple suivant montre une fonction définie par l’utilisateur qui utilise l’intégration d’accès externe my_app_prefix_eai_rule.

CREATE OR REPLACE FUNCTION setup.EXTERNAL_ACCESS_UDF(hostname STRING)
  RETURNS STRING
  LANGUAGE JAVA
  HANDLER='TestHostNameLookup.compute'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_app_prefix_eai_rule)
  AS
  '
      import java.net.InetAddress;
      import java.net.UnknownHostException;
      class TestHostNameLookup {{
          public static String compute(String hostname) throws Exception {{
              InetAddress addr = null;
              try {
                  addr = InetAddress.getByName(hostname);
              } catch(UnknownHostException ex) {
                  return "Hostname lookup failed";
              }
              return "Hostname lookup successful";
          }
      }
';
GRANT USAGE ON FUNCTION setup.EXTERNAL_ACCESS_UDF(STRING)
  TO APPLICATION ROLE app_public;

Cette fonction définit la valeur de EXTERNAL_ACCESS_INTEGRATIONS sur l’intégration d’accès externe créée précédemment.

Cette fonction utilise le paquet Java InetAddress pour chercher le nom d’hôte transmis à la procédure. Le nom d’hôte fourni doit correspondre à l’une des valeurs fournies dans la propriété VALUE_LIST des règles de réseau utilisées par l’intégration d’accès externe.

Créer une spécification d’application pour une intégration d’accès externe¶

L’exemple suivant montre comment créer une spécification d’application pour une intégration d’accès externe :

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
  HOST_PORTS = ('example.com')

Cette commande crée une spécification d’application nommée spec_app_eai.

Approuver la spécification d’application dans le compte de consommateur¶

Une fois que le fournisseur a configuré l’application pour créer la règle de réseau, l’intégration d’accès externe et la spécification d’application, les consommateurs peuvent consulter la spécification d’application et l’approuver ou la refuser selon les besoins lors de la configuration de l’application. Pour plus d’informations, voir Approuver des connexions à des ressources externes à l’aide de spécifications d’application.