カテゴリ：: ユーザーとセキュリティ DDL （サードパーティのサービス統合）

CREATE API INTEGRATION¶

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

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

クラウドプラットフォームプロバイダー（例：Amazon AWS）。

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

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

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

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

こちらもご参照ください。: ALTER API INTEGRATION 、 DROP INTEGRATION 、 SHOW INTEGRATIONS 、外部関数、 CREATE EXTERNAL FUNCTION

このトピックの内容：

構文
必須パラメーター
オプションのパラメーター
アクセス制御の要件
使用上の注意
例

構文¶

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

Amazon API Gatewayの場合¶

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

aws_api_gateway、 aws_private_api_gateway、 aws_gov_api_gateway または aws_gov_private_api_gateway を引用符で囲むことはできません。

Azure API Managementの場合¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = azure_api_management
    AZURE_TENANT_ID = '<tenant_id>'
    AZURE_AD_APPLICATION_ID = '<azure_application_id>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ( '<...>' )
    [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;

azure_api_management を引用符で囲むことはできません。

Google Cloud API Gatewayの場合¶

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

google_api_gateway を引用符で囲むことはできません。

必須パラメーター¶

Amazon API Gatewayの場合¶

integration_name

API 統合の名前を指定します。この名前はオブジェクト識別子のルールに従います。名前は、使用するアカウントの API 統合間において一意である必要があります。

provider_info

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

aws_api_gateway: 地域のエンドポイントを使用するAmazon API Gatewayの場合。

aws_private_api_gateway: プライベートエンドポイントを使用するAmazon API Gatewayの場合。

aws_gov_api_gateway: 米国政府の GovCloud エンドポイントを使用するAmazon API Gatewayの場合。

aws_gov_private_api_gateway: プライベートエンドポイントでもある米国政府の GovCloud エンドポイントを使用するAmazon API Gatewayの場合。

iam_role

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

api_key

API キー（別名「サブスクリプションキー」）。

ENABLED = < TRUE | FALSE >

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

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

デフォルトは TRUE です。

API_ALLOWED_PREFIXES = (...)

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

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

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

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

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

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

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

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

Microsoft Azure API Managementサービス¶

integration_name

API 統合の名前を指定します。この名前はオブジェクト識別子のルールに従います。名前は、使用するアカウントの API 統合間において一意である必要があります。

tenant_id

すべてのAzure API Managementインスタンスが属するOffice 365テナントの ID を指定します。API 統合は1つのテナントのみを認証できるため、許可およびブロックされた場所は、すべてこのテナントに属する API Managementインスタンスを参照する必要があります。

テナント ID を見つけるには、Azureポータルにログインして Azure Active Directory » Properties をクリックします。テナント ID が Tenant ID フィールドに表示されます。

azure_application_id

リモートサービス用Azure AD （Active Directory）アプリの「アプリケーション（クライアント）ID」。 Microsoft Azureでの外部関数の作成の指示に従った場合、これは、それらの指示のワークシートに記録した Azure Function App AD Application ID です。

api_key

API キー（別名「サブスクリプションキー」）。

ENABLED = < TRUE | FALSE >

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

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

デフォルトは TRUE です。

API_ALLOWED_PREFIXES = (...)

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

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

https://my-external-function-demo.azure-api.net/my-function-app-name

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

https://my-external-function-demo.azure-api.net/my-function-app-name

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

https://my-external-function-demo.azure-api.net/my-function-app-name/my-http-trigger-function

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

Google Cloud API Gatewayの場合¶

integration_name

API 統合の名前を指定します。この名前はオブジェクト識別子のルールに従います。名前は、使用するアカウントの API 統合間において一意である必要があります。

google_audience

これは、Google API Gatewayに対して認証するための JWT （JSON ウェブトークン）を生成する際のオーディエンスクレームとして使用されます。Googleでの認証の詳細については、Googleサービスアカウント認証のドキュメントをご参照ください。

ENABLED = < TRUE | FALSE >

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

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

デフォルトは TRUE です。

API_ALLOWED_PREFIXES = (...)

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

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

https://my-external-function-demo.uc.gateway.dev/x

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

https://my-external-function-demo.uc.gateway.dev/x

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

https://my-external-function-demo.uc.gateway.dev/x/y

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

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

これらのオプションのパラメーターは、次のそれぞれに適用されます。

Amazon API Gateway。
Azure API Managementサービス。
Google Cloud API Gateway。

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>'

外部関数の説明。

アクセス制御の要件¶

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

権限	オブジェクト	メモ
CREATE INTEGRATION	アカウント	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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

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

使用上の注意¶

API 統合に対する OWNERSHIP または USAGE 権限を持つSnowflakeロールのみが、 API 統合を直接（例： API 統合を指定する外部関数を作成することにより）使用できます。
API 統合オブジェクトは、特定のクラウドプラットフォームアカウントとそのアカウント内のロールに関連付けられていますが、特定の HTTPS プロキシ URL には関連付けられていません。クラウドプロバイダーアカウントで HTTPS プロキシサービスの複数のインスタンスを作成でき、同じ API 統合を使用して、そのアカウントの複数のプロキシサービスを認証できます。
Snowflakeアカウントには、たとえば、異なるクラウドプラットフォームアカウント用の複数の API 統合オブジェクトを含めることができます。
複数の外部関数は同じ API 統合オブジェクトを使用できるため、同じ HTTPS プロキシサービスを使用できます。
メタデータについて。

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールドをご参照ください。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、古いオブジェクトの削除と新しいオブジェクトの作成が1つのトランザクションで処理されます。

例¶

この例は、 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';