앱 사양을 사용하여 컨슈머의 외부 엔드포인트 요청¶

|native-app|에서 외부 서비스에 액세스¶

일부 |native-apps|는 Snowflake 외부에서 존재하는 리소스에 연결해야 합니다. Snowflake는 필요한 외부 연결 타입에 따라 서로 다른 오브젝트를 제공합니다.

자동 권한 부여 를 사용할 경우, 앱은 설정 스크립트 실행 시 이러한 오브젝트를 생성하는 데 필요한 권한을 보유합니다. 그러나 이러한 오브젝트는 Snowflake 외부와의 연결을 허용하므로, 컨슈머는 앱 구성 시 이러한 연결을 승인해야 합니다.

앱 사양을 통해 공급자는 앱이 요청하는 연결 정보를 지정할 수 있습니다. 컨슈머가 앱을 설치할 때, 앱 사양을 검토하고 필요에 따라 승인하거나 거절합니다.

앱 사양 워크플로¶

앱 사양을 구성하고 사용하는 일반적인 작업 흐름은 다음과 같습니다.

1. 공급자는 앱에 대한 권한 자동 부여 를 구성합니다. 이를 통해 컨슈머는 앱이 외부 액세스 통합을 생성하도록 허용할 수 있습니다.

   참고

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

2. 공급자는 매니페스트 파일에 CREATE EXTERNAL ACCESS INTEGRATION 권한을 추가 합니다.

3. 공급자는 설정 스크립트에 SQL 문을 추가하여 필요에 따라 다음 오브젝트를 만듭니다.

   • 네트워크 규칙

   • 외부 액세스 통합

   • 보안 통합

   • 앱 사양

   설정 스크립트는 앱이 설치되거나 업그레이드될 때 또는 실행 중에 앱 사양 및 기타 오브젝트를 생성합니다.

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

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

앱이 CREATE EXTERNAL ACCESS INTEGRATION 권한을 요청하도록 구성하려면 매니페스트 파일의 privileges 섹션에 다음 코드를 추가합니다.

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

매니페스트 파일의 privileges 섹션에 이 항목이 있으면 앱이 외부 액세스 통합을 사용하는 것입니다. 앱이 권한 부여를 자동화하려면 매니페스트 파일에서 manifest_version: 2 도 설정해야 합니다.

설정 스크립트에 네트워크 규칙 및 외부 액세스 통합 추가¶

외부 액세스 통합은 특정 외부 네트워크 위치에 대한 액세스를 가능하게 하는 Snowflake 오브젝트입니다. 외부 액세스 통합에는 앱이 액세스할 수 있는 외부 위치를 지정하는 네트워크 규칙 목록이 포함됩니다.

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

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

HOST_PORT 및 VALUE_LIST 속성은 네트워크 규칙이 유효한 도메인, 포트 또는 포트 범위를 가리켜야 함을 나타냅니다. 앱이 설치되거나 업그레이드될 때, 컨슈머는 해당 앱이 이러한 도메인이나 포트를 사용할 수 있도록 권한을 부여합니다.

앱에 대한 외부 액세스 통합을 생성하려면 다음 예제시와 같이 설정 스크립트에 CREATE EXTERNAL ACCESS INTEGRATION 명령을 추가합니다.

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

이 명령은 my_app_prefix_eai_rule 이라는 외부 액세스 통합을 생성하여 앱이 외부 리소스 또는 엔드포인트에 액세스할 수 있도록 합니다. setup.my_network_rule 네트워크 규칙을 사용합니다.

설정 스크립트에 보안 통합 추가¶

보안 통합을 통해 앱은 OAuth과 같은 서드 파티 인증 서비스에 연결할 수 있습니다. 앱에 대한 보안 통합을 생성하려면 다음 예제와 같이 CREATE SECURITY INTEGRATION(External API 인증) 명령을 사용합니다.

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;

이 예제는 클라이언트 자격 증명과 OAuth를 사용하여 Microsoft SharePoint에 연결하는 보안 통합을 생성하는 방법을 보여줍니다. OAuth 공급자에 연결하는 다른 지원되는 방법에 대해서는 CREATE SECURITY INTEGRATION(External API 인증) 섹션을 참조하세요.

설정 스크립트에서 앱 사양 만들기¶

앱 사양을 생성하기 위해 공급자는 설정 스크립트에 ALTER APPLICATION SET SPECIFICATIONS 명령을 추가합니다.

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');

앱 사양 사용을 위한 모범 사례¶

자동 권한 부여 는 앱이 외부 액세스 통합을 생성하는 데 필요한 권한을 확보하도록 보장합니다. 그러나 컨슈머는 외부 엔드포인트와의 연결을 가능하게 하는 앱 사양을 거부할 수 있습니다. 앱을 개발할 때 공급자는 앱 사양이 승인되지 않을 수 있는 상황을 고려해야 합니다.

예를 들어, 앱이 외부 액세스 통합을 위해 여러 네트워크 포트를 사용하도록 요청할 수 있지만, 컨슈머는 단 하나만 허용할 수 있습니다. 네트워크 포트를 사용할 수 없는 경우 발생하는 오류를 처리하는 논리를 앱에 포함해야 합니다. 또한 모범 사례는 발생할 수 있는 모든 HTTP 예외를 처리하는 것입니다.

앱 사양과 함께 콜백 함수 사용¶

일부 상황에서 앱은 컨슈머가 앱 사양을 승인했는지 또는 거절했는지를 알아야 할 수 있습니다. 예를 들어, 앱은 오브젝트를 생성하기 전에 앱 사양이 승인될 때까지 기다려야 할 수 있습니다.

이러한 상황을 처리하기 위해, |naf|는 공급자가 앱 사양을 승인하거나 거부할 때 실행되는 콜백 저장 프로시저를 정의할 수 있는 메커니즘을 제공합니다.

공급자는 다음 예제시와 같이 매니페스트 파일에 저장 프로시저를 추가할 수 있습니다.

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

이 예제는 callbacks.on_spec_update 라는 저장 프로시저를 매니페스트 파일에 추가하는 방법을 보여줍니다. 설정 스크립트에서 공급자는 다음 예제와 같이 저장 프로시저를 추가할 수 있습니다.

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...

이 예제는 callbacks.on_spec_update 라는 저장 프로시저의 서명을 보여줍니다. 이 프로시저 본문에서 공급자는 앱 사양 상태 확인, 오브젝트 생성 및 필요한 작업을 수행하는 데 필요한 코드를 포함합니다.