CREATE EXTERNAL ACCESS INTEGRATION

外部アクセス統合 を作成し、 UDF またはプロシージャハンドラーから外部ネットワークロケーションにアクセスできるようにします。

こちらもご参照ください。

ALTER EXTERNAL ACCESS INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , DESCRIBE INTEGRATION

構文

CREATE [ OR REPLACE ] EXTERNAL ACCESS INTEGRATION <name>
  ALLOWED_NETWORK_RULES = ( <rule_name_1> [, <rule_name_2>, ... ] )
  [ ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( { <integration_name_1> [, <integration_name_2>, ... ] | none } ) ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name_1> [, <secret_name_2>, ... ] | all | none } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
Copy

必須パラメーター

name

外部アクセス統合の識別子。

識別子の値はアルファベットで始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子は、大文字と小文字が区別されます。

詳細については、 識別子の要件 をご参照ください。

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ])

許可された ネットワークルール を指定します。指定できるのはエグレスルールのみです。

ENABLED = { TRUE | FALSE }

この統合を有効にするか無効にするかを指定します。統合が無効になっている場合、それに依存するハンドラーコードは外部ネットワークロケーションに到達できなくなります。

値では大文字と小文字が区別されません。

デフォルトは TRUE です。

オプションのパラメーター

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] | none )

OAuth 認証サーバが UDF またはプロシージャで使用するシークレットを発行したセキュリティ統合を指定します。セキュリティ統合は、 外部 API 統合に使用される型 にする必要があります。

このパラメーター値は、次のいずれかにする必要があります。

  • リストされた統合のいずれかを許可するための1つ以上のSnowflakeセキュリティ統合名。

  • none は、統合を許可しません。

このパラメーターで指定されるセキュリティ統合と、ALLOWED_AUTHENTICATION_SECRETS パラメーターで指定されるシークレットは、この外部アクセス統合を使用する UDF またはプロシージャでシークレットの使用を許可する方法です。詳細については、 使用上の注意 をご参照ください。

セキュリティ統合に関する参照情報については、 CREATE SECURITY INTEGRATION （外部 API 認証） をご参照ください。

ALLOWED_AUTHENTICATION_SECRETS = ( secret_name [, secret_name ... ] | all | none )

UDF またはプロシージャハンドラーコードが、許可されたネットワークルールで参照される外部ネットワークロケーションにアクセスするときに使用できるシークレットを指定します。

このパラメーター値は、次のいずれかにする必要があります。

  • 1つ以上のSnowflakeシークレット名で、リストされた任意のシークレットを許可します。

  • all は、任意のシークレットを許可します。

  • none は、シークレットを許可しません。

ALLOWED_API_AUTHENTICATION_INTEGRATIONS パラメーターは、許可されるシークレットも指定できます。詳細については、 使用上の注意 をご参照ください。

シークレットに関する参照情報については、 CREATE SECRET をご参照ください。

COMMENT = 'string_literal'

外部アクセス統合のコメントを指定します。

デフォルト: 値なし

アクセス制御の要件

この SQL コマンドの実行に使用される ロール には、少なくとも次の 権限 が必要です。

権限

オブジェクト

メモ

CREATE INTEGRATION

アカウント

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

USAGE

シークレット

統合によって参照されるすべてのシークレットに必要です。

USAGE

スキーマ

統合によって参照されるシークレットを含むすべてのスキーマに必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

  • 以下のように、2つの外部アクセス統合パラメーターを使用して、 UDF またはプロシージャによるシークレットの使用を許可できます。

    • ALLOWED_AUTHENTICATION_SECRETS パラメーターを使用。シークレットをパラメーター値として指定したり、パラメーターの値を all に設定したりして、ハンドラーコードが任意のシークレットを使用できるようにします。

    • ALLOWED_API_AUTHENTICATION_INTEGRATIONS パラメーターを使用。 シークレット は、シークレット自体がこのパラメーターで指定された名前のセキュリティ統合を指定する場合に使用が許可されます。シークレットは、 API_AUTHENTICATION パラメーターでセキュリティ統合を指定します。言い換えると、シークレットと外部アクセス統合の両方がセキュリティ統合を指定する場合、シークレットは外部アクセス統合を指定する関数やプロシージャでの使用が許可されます。

    この2つの選択肢は互いに独立して機能することに注意してください。どちらか（あるいは両方）のパラメーターがそれを許可していれば、もう一方のパラメーターに指定された値に関係なく、シークレットは許可されます。たとえば、パラメーターの一方を none に設定しても、もう一方のパラメーターで指定されたシークレットがハンドラーコードで使用されることを防ぐことはできません。

  • ホスト名を使用してネットワークルールを指定できますが、Snowflakeは IP の粒度でルールを適用します。Snowflakeはアプリケーションのトラフィックを検査しないため、外部ロケーションのホストに正規のサービスがあり、同じホスト上の他のサービスに接続できないことを確認するのはお客様の責任となります。インターネット・エンドポイントとの通信には、可能な限り、 HTTPS や TLS などの安全なプロトコルを使用する必要があります。

  • メタデータについて:

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

例

Google翻訳 API へのアクセスを提供する外部アクセス統合を作成します。

より包括的な例については、 外部アクセス統合の作成と使用 をご参照ください。

  1. 認証情報を表すシークレットを作成します。

    シークレットを作成するには、現在のスキーマに対する CREATE SECRET 権限を持つロールが割り当てられている必要があります。このコマンドでサポートされている他の種類のシークレットについては、 CREATE SECRET をご参照ください。この例では、 google_translate_oauth はセキュリティ統合を意味します。詳細については、 CREATE SECURITY INTEGRATION （外部 API 認証） をご参照ください。

    CREATE OR REPLACE SECRET oauth_token
  TYPE = OAUTH2
  API_AUTHENTICATION = google_translate_oauth
  OAUTH_REFRESH_TOKEN = 'my-refresh-token';
    Copy

  2. UDF の開発者が使えるように、シークレットに対する READ 権限を developer ロールに付与します。

    開発者がシークレットを使用する際に必要となるロールを作成します。

    USE ROLE USERADMIN;
CREATE OR REPLACE ROLE developer;
    Copy

    developer ロールに READ 権限を付与します。

    USE ROLE SECURITYADMIN;
GRANT READ ON SECRET oauth_token TO ROLE developer;
    Copy

  3. 外部ネットワークの場所を表すネットワークルールを作成します。 CREATE NETWORK RULE で説明されている権限を持つロールを使用します。

    USE ROLE SYSADMIN;
CREATE OR REPLACE NETWORK RULE google_apis_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('translation.googleapis.com');
    Copy

  4. シークレットとネットワークルールを使用して、外部アクセス統合を作成します。

    USE ROLE ACCOUNTADMIN;
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
  ALLOWED_NETWORK_RULES = (google_apis_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (oauth_token)
  ENABLED = true;
    Copy

  5. UDF の開発者が使えるように、統合に対する USAGE 権限を developer ロールに付与します。

    GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
    Copy

  6. 指定されたテキストを指定された言語のフレーズに翻訳する UDF google_translate_python を作成します。詳細については、 関数またはプロシージャでの外部アクセス統合の使用 をご参照ください。

    USE ROLE developer;

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
HANDLER = 'get_translation'
EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration)
PACKAGES = ('snowflake-snowpark-python','requests')
SECRETS = ('cred' = oauth_token )
AS
$$
import _snowflake
import requests
import json
session = requests.Session()
def get_translation(sentence, language):
  token = _snowflake.get_oauth_access_token('cred')
  url = "https://translation.googleapis.com/language/translate/v2"
  data = {'q': sentence,'target': language}
  response = session.post(url, json = data, headers = {"Authorization": "Bearer " + token})
  return response.json()['data']['translations'][0]['translatedText']
$$;
    Copy

  7. USAGE 権限を google_translate_python 関数に付与して、ユーザーロールを持つ人がその関数を呼び出せるようにします。

    GRANT USAGE ON FUNCTION google_translate_python(string, string) TO ROLE user;
    Copy

  8. フレーズを翻訳するには google_translate_python 関数を実行します。

    USE ROLE user;
SELECT google_translate_python('Happy Thursday!', 'zh-CN');
    Copy

    これは以下のような出力を生成します。

    -------------------------------------------------------
| GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
-------------------------------------------------------
| 快乐星期四！                                          |
-------------------------------------------------------
言語: 日本語