カテゴリ:

ユーザーとセキュリティ DDL (サードパーティのサービス統合)

CREATE API INTEGRATION

アカウントに新しい API 統合を作成するか、既存の API 統合を置き換えます。

API 統合オブジェクトは、 HTTPS プロキシサービスに関する情報を保存します。

  • クラウドプラットフォームプロバイダー(例:Amazon AWS)。

  • プロキシサービスのタイプ(クラウドプラットフォームプロバイダーが複数のタイプのプロキシサービスを提供している場合)。

  • プロキシサービスを使用するための十分な権限を持つ、クラウドプラットフォームのロールの識別子とアクセス認証情報。たとえば、 AWS では、ロールの ARN (Amazonリソース名)が識別子およびアクセス認証情報として機能します。

    このクラウドユーザーに適切な権限が付与されると、Snowflakeはこのユーザーを使用してプロキシサービス(クラウドプラットフォームのネイティブ HTTPS プロキシサービスのインスタンス、たとえばAmazon AWS API Gatewayのインスタンス)のリソースにアクセスできます。

  • API 統合オブジェクトは、それらのプロキシサービスで許可された(およびオプションでブロックされた)エンドポイントとリソースも指定します。

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

ALTER API INTEGRATIONDROP INTEGRATIONSHOW INTEGRATIONS外部関数CREATE EXTERNAL FUNCTION

このトピックの内容:

構文

構文はクラウドプラットフォームごとに異なります。

Amazon AWS API Gatewayの場合

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = <provider_info>
    API_AWS_ROLE_ARN = '<iam_role>'
    ENABLED = { TRUE | FALSE }
    API_ALLOWED_PREFIXES = ('<...>')
    [ API_BLOCKED_PREFIXES = ('<...>') ]
    [ COMMENT = '<string_literal>' ]
    ;

必須パラメーター

Amazon AWS API Gatewayの場合

統合名

API 統合の名前を指定します。この名前は オブジェクト識別子 のルールに従います。名前は、現在のスキーマの API 統合間で一意である必要があります。

プロバイダー情報

HTTPS プロキシサービスタイプを指定します。有効な値:

  • aws_api_gateway :Amazon AWS API Gateway用。

iamロール

Amazon AWS の場合、これはクラウドプラットフォームのロールの ARN (Amazonリソース名)です。

ENABLED = < TRUE | FALSE >

この API 統合を有効にするか無効にするかを指定します。API 統合が無効になっている場合、その統合に依存する外部関数はすべて機能しません。

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

デフォルトは TRUE です。

API_ALLOWED_PREFIXES = (...)

統合を使用して1つ以上の HTTPS プロキシサービスエンドポイント(例:Amazon AWS API Gateway)、およびそれらのプロキシ内のリソースを参照する外部関数を明示的に制限します。プレフィックスとして扱われる URLs のコンマ区切りリストをサポートします(詳細については、以下を参照)。

API_ALLOWED_PREFIXES = (...) の各 URL はプレフィックスとして扱われます。たとえば、次のように指定したとします。

https://xyz.amazonaws.com/production/

つまり、すべてのリソースが

https://xyz.amazonaws.com/production/

許可されています。たとえば、次は許可されています。

https://xyz.amazonaws.com/production/ml1

セキュリティを最大化するには、許可される場所を実用範囲内でできるだけ狭く制限する必要があります。

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

API_BLOCKED_PREFIXES = (...)

Snowflakeからの呼び出しが許可されていない HTTPS プロキシサービスのエンドポイントとリソースを一覧表示します。

場所の可能な値は、上記の API_ALLOWED_PREFIXES の場合と同じルールに従います。

API_BLOCKED_PREFIXES API_ALLOWED_PREFIXES よりも優先されます。プレフィックスが両方に一致する場合は、ブロックされます。つまりSnowflakeでは、 API_ALLOWED_PREFIXES に一致するすべての値が許可されます。ただし、値が API_BLOCKED_PREFIXES にも一致する場合は 除外 されます。

値が API_ALLOWED_PREFIXES の外にある場合は、明示的にブロックする必要はありません。

COMMENT = '<string_literal>'

外部関数の説明。

使用上の注意

  • ACCOUNTADMIN のロールまたはグローバル CREATE INTEGRATION 権限があるロールを持つSnowflakeユーザーのみが、 CREATE API INTEGRATION を実行できます。

  • API 統合に対する OWNERSHIP または USAGE 権限を持つSnowflakeロールのみが、たとえば、 API 統合を指定する外部関数を作成することにより、 API 統合を直接使用できます。

  • API 統合オブジェクトは、特定のクラウドプラットフォームアカウントとそのアカウント内のロールに関連付けられていますが、特定の HTTPS プロキシ URL には関連付けられていません。クラウドプロバイダーアカウントで HTTPS プロキシサービスの複数のインスタンスを作成でき、同じ API 統合を使用して、そのアカウントの複数のプロキシサービスを認証できます。

  • Snowflakeアカウントには、たとえば、異なるクラウドプラットフォームアカウント用の複数の API 統合オブジェクトを含めることができます。

  • 複数の外部関数は同じ API 統合オブジェクトを使用できるため、同じ HTTPS プロキシサービスを使用できます。

  • AWS では、外部関数に地域エンドポイントが必要です。詳細については、 Amazon AWS API Gateway をご参照ください。

この例は、 API 統合の作成と、後続の CREATE EXTERNAL FUNCTION ステートメントにおけるその API 統合の使用を示しています。

create or replace api integration demonstration_external_api_integration_01
    api_provider=aws_api_gateway
    api_aws_role_arn='arn:aws:iam::123456789012:role/my_cloud_account_role'
    api_allowed_prefixes=('https://xyz.execute-api.us-west-2.amazonaws.com/production')
    enabled=true;

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo';