컨슈머로부터 참조 및 오브젝트 수준 권한 요청하기¶

참조 정보¶

상황에 따라서는 설치된 Snowflake Native App 이 APPLICATION 오브젝트 외부에 있는 컨슈머 계정의 기존 오브젝트에 액세스해야 할 때도 있습니다. 예를 들어, 앱은 컨슈머 데이터베이스의 기존 테이블에 액세스해야 할 수 있습니다.

이 상황에서는 앱이 컨슈머 계정의 스키마와 오브젝트의 이름을 확인할 수 없어 컨슈머가 오브젝트에 대한 액세스 권한을 APPLICATION 오브젝트에 부여하는 것으로는 충분하지 않습니다.

Snowflake Native App 이 APPLICATION 오브젝트 외부의 기존 오브젝트에 액세스할 수 있도록 Snowflake Native App Framework 는 고객이 오브젝트의 이름과 스키마를 지정하고 오브젝트에 대한 액세스를 활성화할 수 있는 참조를 제공합니다.

매니페스트 파일에서 참조 정의하기¶

다음 예에서는 APPLICATION 오브젝트 외부에 있는 컨슈머 계정의 테이블에 대한 manifest.yml 파일에 참조를 정의하는 방법을 보여줍니다.

references:
  - consumer_table:
      label: "Consumer table"
      description: "A table in the consumer account that exists outside the APPLICATION object."
      privileges:
        - INSERT
        - SELECT
      object_type: TABLE
      multi_valued: false
      register_callback: config.register_single_reference

이 예에서는 컨슈머 계정의 테이블에 대한 INSERT 및 SELECT 권한이 필요한 consumer_table 이라는 참조를 정의합니다. register_callback 속성은 컨슈머 테이블을 이 참조 정의에 바인딩하는 데 사용되는 저장 프로시저를 지정합니다.

여러 개의 컨슈머 오브젝트를 동일한 참조에 바인딩하려면 multi_valued 를 사용합니다. 이 속성이 지정되면 단일 값 참조가 있는 오브젝트에서 동일한 작업이 수행됩니다. 이 속성은 다중값 참조가 있는 오브젝트에도 사용할 수 있습니다. Snowflake Native App Framework 참조 작업에 대해 자세히 알아보려면 지원되는 참조 함수 를 참조하십시오.

Reference definition '<REF_DEF_NAME>' cannot be found in the current version of the application '<APP_NAME>'

참조용 콜백 저장 프로시저 만들기¶

manifest.yml 파일에서 참조를 정의한 후 공급자는 설정 스크립트에 저장 프로시저를 추가하여 참조에 대한 콜백을 등록해야 합니다.

다음 예제에서는 매니페스트 파일에서 참조 정의하기 에 표시된 참조에 대한 콜백을 처리하는 데 사용되는 저장 프로시저를 보여줍니다.

CREATE APPLICATION ROLE app_admin;

CREATE OR ALTER VERSIONED SCHEMA config;
GRANT USAGE ON SCHEMA config TO APPLICATION ROLE app_admin;

CREATE PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(ref_name STRING, operation STRING, ref_or_alias STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS $$
    BEGIN
      CASE (operation)
        WHEN 'ADD' THEN
          SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'REMOVE' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_ALL_REFERENCES(:ref_name);
      ELSE
        RETURN 'unknown operation: ' || operation;
      END CASE;
      RETURN NULL;
    END;
  $$;

GRANT USAGE ON PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;

이 예에서는 저장 프로시저에 인자로 전달되는 참조에 대해 특정 작업을 수행하는 시스템 함수를 호출하는 REGISTER_SINGLE_REFERENCE 이라는 저장 프로시저를 만듭니다.

오브젝트 구성을 요청하기 위한 콜백 저장 프로시저를 만듭니다.¶

일부 오브젝트 유형의 경우 공급자는 추가 구성을 제공하기 위해 설정 스크립트에 저장 프로시저를 추가해야 합니다. 이 콜백은 컨슈머가 Snowsight 를 사용하여 참조를 허용할 때 사용됩니다.

다음 예제는 매니페스트 파일에서 참조 정의하기 에 표시된 참조에 대한 구성 콜백 저장 프로시저를 정의하는 방법을 보여줍니다.

CREATE OR REPLACE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(ref_name STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS
  $$
  BEGIN
    CASE (ref_name)
      WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "host_ports":["google.com"],
            "allowed_secrets" : "LIST",
            "secret_references":["CONSUMER_SECRET"]}}';
      WHEN 'CONSUMER_SECRET' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "type" : "OAUTH2",
            "security_integration": {
              "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
              "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
              "oauth_authorization_endpoint":
                "https://accounts.google.com/o/oauth2/auth"}}}';
     END CASE;
     RETURN '';
   END;
   $$;

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

이 예제에서는 EXTERNAL ACCESS INTEGRATION 또는 SECRET 참조 유형의 참조를 작성하는 데 사용되는 JSON 형식의 구성을 반환하는 이름이 GET_CONFIGURATION_FOR_REFERENCE 인 저장 프로시저를 만듭니다. switch 문에 있는 항목은 manifest.yml 파일의 참조 이름에 매핑되어야 합니다.

애플리케이션에 정의된 참조 보기¶

공급자가 manifest.yml 파일에 참조를 정의하면 참조가 설치된 Snowflake Native App 의 일부로 포함됩니다.

Snowflake Native App 에 대해 정의된 참조를 보려면 다음 예와 같이 SHOW REFERENCES 명령을 실행하십시오.

SHOW REFERENCES IN APPLICATION hello_snowflake_app;

애플리케이션에 오브젝트 바인딩하기¶

컨슈머는 Snowflake Native App 에 대한 참조 정의를 본 후 다음 예와 같이 SYSTEM$REFERENCE 시스템 함수를 실행하여 참조를 생성합니다.

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', 'persistent', 'select', 'insert');

이 명령은 참조의 식별자를 반환합니다. 컨슈머는 다음 예와 같이 식별자를 참조의 콜백 저장 프로시저에 전달할 수 있습니다.

CALL app.config.register_single_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));

이 예에서 consumer_table 은 manifest.yml 파일에 정의된 참조의 이름입니다. 컨슈머가 참조를 연결하는 저장 프로시저를 실행하면 Snowflake Native App 이 컨슈머 계정의 테이블에 액세스할 수 있습니다.

이전 섹션 의 콜백 저장 프로시저는 다음 예와 같이 SYSTEM$SET_REFERENCE 시스템 함수를 호출합니다.

SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);

참조와 관련된 다른 시스템 함수에 대해서는 지원되는 참조 함수 섹션을 참조하십시오.

참조 사용 시 고려 사항¶

버전 간에 참조 정의를 수정하지 않는 것이 좋습니다. 예를 들어 권한을 SELECT에서 SELECT, INSERT로 변경하기 위해 새 버전에서 참조 정의를 업데이트하려면 다른 이름으로 새 참조 정의를 정의해야 합니다. 업데이트된 Snowflake Native App 은 앱의 새 버전에서 이 새 참조를 사용할 수 있습니다.

예를 들어 참조를 변수에 할당하기 위해 다른 오브젝트 내에 참조를 포함하려면 참조가 컨슈머 계정의 오브젝트에 이미 바인딩되어 있어야 합니다. 예를 들어 먼저 참조를 컨슈머 웨어하우스에 바인딩하지 않으면 작업을 생성할 수 없습니다.

Snowflake Native App 에서 참조를 사용하는 예¶

다음 섹션에서는 다양한 컨텍스트에서 참조를 사용하는 예를 제시합니다.

SELECT * FROM reference('consumer_table');

SELECT reference('encrypt_func')(t.c1) FROM consumer_table t;

CALL reference('consumer_proc')(11, 'hello world');

INSERT INTO reference('data_export')(C1, C2)
  SELECT T.C1, T.C2 FROM reference('other_table')

COPY INTO reference('the_table') ...

DESCRIBE TABLE reference('the_table')

CREATE TASK app_task
  WAREHOUSE = reference('consumer_warehouse')
  ...;

ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');

CREATE VIEW app_view
  AS SELECT reference('function')(T.C1) FROM reference('table') AS T;

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  AS $$ select reference('consumer_func')(x) $$;

CREATE EXTERNAL FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  API_INTEGRATION = reference('app_integration');

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  EXTERNAL_ACCESS_INTEGRATIONS = (reference('consumer_external_access_integration'), ...);
  SECRETS = ('cred1' = reference('consumer_secret'), ...);

CREATE ROW ACCESS POLICY app_policy
  AS (sales_region varchar) RETURNS BOOLEAN ->
  'sales_executive_role' = reference('get_sales_team')
    or exists (
      select 1 from reference('sales_table')
        where sales_manager = reference('get_sales_team')()
        and region = sales_region
      );

구성 콜백 응답의 JSON 형식¶

구성 콜백 함수는 JSON 형식의 응답을 반환합니다. 외부 액세스 통합과 시크릿 참조에 따라 반환되는 JSON 형식은 다릅니다.

{
  "type": "CONFIGURATION",
  "payload": {
    "host_ports": ["host_port_1", ...],
    "allowed_secrets": "NONE|ALL|LIST",
    "secret_references": ["ref_name_1", ...]
  }
}

{
  "type": "CONFIGURATION",
    "payload": {
            "type": "OAUTH2",
            "security_integration": {
                    "oauth_scopes": ["scope_1", "scope_2"],
                    "oauth_token_endpoint" : "token_endpoint",
                    "oauth_authorization_endpoint" : "auth_endpoint"
            }
    }
}

 {
   "type": "ERROR",
   "payload":{
     "message": "The reference is not available for configuration ..."
  }
}

지원되는 참조 함수¶

Snowflake Native App Framework 는 참조와 관련된 다양한 작업을 수행하는 다음 함수를 지원합니다.