Example - Access external endpoint using app specifications¶

Set the version of the manifest file¶

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

Request the CREATE EXTERNAL ACCESS INTEGRATION privilege in the manifest file¶

The CREATE EXTERNAL ACCESS INTEGRATION privilege allows the app to create an external access integration during installation or upgrade. To request this privilege from the consumer, add the following entry to the manifest file:

privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Required to create eai integrations so we can simplify your life"

CREATE EXTERNAL ACCESS INTEGRATION privilege is automatically granted to the app before installation or upgrade and has the following benefits:

• Consumers do not have to manually create the external access integration required by the app and approve access using references.

• Providers do not have to write code that checks for the existence of the CREATE EXTERNAL ACCESS INTEGRATION privilege before proceeding to create the object during installation or upgrade.

Create a network rule for the external access integration¶

An external access integration requires a network rule that defines the external endpoints. For example, to create a network rule, add the CREATE NETWORK RULE command to the setup script of the app:

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

This command creates a network rule that defines an outgoing request (egress) to the host port example.com.

Create an external access integration¶

After creating a network rule in the setup script, use the CREATE EXTERNAL ACCESS INTEGRATION command to create an external access integration as shown in the following example:

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

Create a user-defined function to access the external endpoint¶

After creating the external access integration, the setup script can create user-defined functions and stored procedures that use it to connect to the endpoints defined in the network rule.

The following example shows a user-defined function that uses the my_app_prefix_eai_rule external access integration.

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;

This function sets the value of the EXTERNAL_ACCESS_INTEGRATIONS to the external access integration created previously.

This function uses the InetAddress Java package to lookup the hostname passed to the procedure. The hostname provided must match one the values provided in the VALUE_LIST property of the network rules used by the external access integration.

Create the app specification¶

An app can create an app specification during installation or upgrade or at runtime from a stored procedure. The following example shows how to use the ALTER APPLICATION SET SPECIFICATIONS command to create an app specification:

ALTER APPLICATION SET SPECIFICATION my_app_specification
        TYPE = EXTERNAL_ACCESS
        LABEL = 'An external api'
        DESCRIPTION = 'Used to connect to an external API'
        HOST_PORTS  = 'example.com';