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 réseau et une EAI, qui utilise des règles réseau pour restreindre l’accès à des emplacements 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 utiliser une EAI, suivez les étapes suivantes :

• Pour demander des privilèges au consommateur afin de créer une EAI, utilisez l’octroi automatique de privilèges.

• Ajoutez une EAI à 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 une EAI¶

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

   Note

   App specifications require that manifest_version: 2 be set in the manifest file.

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 :

   • 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. When configuring the app, consumers review and approve the host ports and external services. For more information on how consumers view and approve app specifications, see Approve app specifications.

Définition de la spécification d’application pour une EAI¶

La définition de la spécification d’application pour une EAI 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¶

To enable automated granting of privileges for an app, set the version at the beginning of the manifest file as shown in the following example:

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 EAI to connect to an external service."
  ...
  

  Copy

Si vous définissez manifest_version sur 2 dans le fichier manifeste, Snowflake accorde automatiquement le privilège CREATE EXTERNAL ACCESS INTEGRATION sur l’application lors de l’installation ou de la mise à niveau.

Ajouter une règle réseau et une EAI au script d’installation¶

Les EAIs sont les objets Snowflake qui permettent l’accès à des emplacements réseau externes spécifiques et contiennent une liste de règles 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;
  

  Copy

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, les consommateurs accordent l’autorisation à l’application d’utiliser ces domaines ou ports.

Créer une EAI¶

• Pour créer une EAI 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;
  

  Copy

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

Après avoir créé l’EAI, 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 réseau.

L’exemple suivant montre une fonction définie par l’utilisateur qui utilise l’EAI 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 des EXTERNAL_ACCESS_INTEGRATIONS sur l’EAI 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 réseau utilisées par l’EAI.

Création d’une spécification d’application pour une EAI¶

L’exemple suivant montre comment créer une spécification d’application pour une EAI :

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

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 réseau, l’EAI 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 Approve app specifications.