외부 액세스 통합(EAIs) 요청(앱 사양 포함)¶

앱에서 외부 엔드포인트에 액세스하기¶

To access an external endpoint, an app must create a network rule and an EAI, which uses network rules to restrict access to specific external network locations. Network rules define the external endpoints that an app can access.

To configure an app to use an EAI, follow these steps:

• To request privileges from the consumer to create an EAI, use automated granting of privileges.

• Add an EAI to an app.

• 애플리케이션 사양 을 사용하여 외부 엔드포인트에 연결하기 위한 권한을 컨슈머에게 요청합니다.

App specification workflow for an EAI¶

1. Providers configure automated granting of privileges for the app. This allows consumers to give permission to an app to create the EAI.

   참고

   앱 사양에 따라 매니페스트 파일을 manifest_version = 2 로 설정해야 합니다.

2. 공급자는 :ref:`CREATE EXTERNAL ACCESS INTEGRATION 권한<label-native_apps_app_spec_add_eai_priv>`을 추가합니다.

3. Providers add SQL statements to the setup script to create the following objects:

   • 네트워크 규칙

   • 외부 액세스 통합

   • 앱 사양

   The setup script creates the app specification and other objects when the app is installed or upgraded or at runtime.

4. 앱을 구성할 때 컨슈머는 호스트 포트 및 기타 외부 서비스를 승인합니다. 컨슈머가 앱 사양을 보고 승인하는 방법에 대한 자세한 내용은 앱 사양을 사용하여 외부 리소스 연결 승인 섹션을 참조하세요.

App specification definition for an EAI¶

The app specification definition for an EAI contains the following entries:

• HOST_PORTS: 앱이 필요로 하는 네트워크 규칙에 정의된 호스트 포트 목록입니다.

• PRIVATE_HOST_PORTS: Snowflake 외부 리소스에 대한 비공개 연결을 허용하는 비공개 호스트 포트 목록입니다.

매니페스트 파일의 버전 설정하기¶

• 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
  

  Copy

매니페스트 파일에 CREATE EXTERNAL ACCESS INTEGRATION 권한을 추가합니다.¶

The CREATE EXTERNAL ACCESS INTEGRATION privilege allows the app to create an external access integration during installation or upgrade.

• To configure an app to request the CREATE EXTERNAL ACCESS INTEGRATION privilege, add the following code to the privileges section of the manifest file:

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

  Copy

If you set the manifest_version to 2 in the manifest file, Snowflake automatically grants the CREATE EXTERNAL ACCESS INTEGRATION privilege to the app during installation or upgrade.

Add a network rule and an EAI to the setup script¶

EAIs are the Snowflake objects that enable access to specific external network locations and contain a list of network rules that specify the external locations that an app can access.

• 앱에 대한 네트워크 규칙을 생성하려면 다음 예제와 같이 설정 스크립트에 CREATE NETWORK RULE 명령을 추가합니다.

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

  Copy

The HOST_PORT and VALUE_LIST properties indicate that the network rule must point to a valid domain, port, or range of ports. When an app is installed or upgraded, consumers grant permission for the app to use these domains or ports.

Create an EAI¶

• To create an EAI for an app, add the CREATE EXTERNAL ACCESS INTEGRATION command to the setup script, 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;
  

  Copy

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

After the EAI is created, 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 EAI:

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 EAI created previously.

This function uses the InetAddress Java package to look up the hostname passed to the procedure. The hostname provided must match one of the values provided in the VALUE_LIST property of the network rules used by the EAI.

Creating an app specification for an EAI¶

The following example shows how to create an app specification for an 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')

This command creates an app specification named eai_app_spec.

컨슈머 계정에서 앱 사양 승인하기¶

After the provider configures the app to create the network rule, EAI, and app specification, consumers can view the app specification and approve or decline it as appropriate when configuring the app. For more information, see 앱 사양을 사용하여 외부 리소스 연결 승인.