- カテゴリ:
ユーザーとセキュリティ DDL (サードパーティのサービス統合)
CREATE API INTEGRATION¶
アカウントに新しい API 統合を作成するか、既存の API 統合を置き換えます。
API 統合オブジェクトは、 HTTPS プロキシサービスに関する情報を保存します。
クラウドプラットフォームプロバイダー(例:Amazon AWS)。
プロキシサービスのタイプ(クラウドプラットフォームプロバイダーが複数のタイプのプロキシサービスを提供している場合)。
プロキシサービスを使用するための十分な権限を持つ、クラウドプラットフォームのロールの識別子とアクセス認証情報。たとえば、 AWS では、ロールの ARN (Amazonリソース名)が識別子およびアクセス認証情報として機能します。
このクラウドユーザーに適切な権限が付与されると、Snowflakeはこのユーザーを使用してプロキシサービス(クラウドプラットフォームのネイティブ HTTPS プロキシサービスのインスタンス、たとえばAmazon AWS API Gatewayのインスタンス)のリソースにアクセスできます。
API 統合オブジェクトは、それらのプロキシサービスで許可された(およびオプションでブロックされた)エンドポイントとリソースも指定します。
- こちらもご参照ください。
ALTER API INTEGRATION 、 DROP INTEGRATION 、 SHOW INTEGRATIONS 、 外部関数 、 CREATE EXTERNAL FUNCTION
このトピックの内容:
構文¶
構文はクラウドプラットフォームごとに異なります。
Amazon AWS API Gatewayの場合¶
CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
API_PROVIDER = { aws_api_gateway | aws_private_api_gateway }
API_AWS_ROLE_ARN = '<iam_role>'
API_ALLOWED_PREFIXES = ('<...>')
[ API_BLOCKED_PREFIXES = ('<...>') ]
ENABLED = { TRUE | FALSE }
[ COMMENT = '<string_literal>' ]
;
aws_api_gateway
または aws_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_ALLOWED_PREFIXES = ( '<...>' )
[ API_BLOCKED_PREFIXES = ( '<...>' ) ]
ENABLED = { TRUE | FALSE }
[ COMMENT = '<string_literal>' ]
;
azure_api_management
を引用符で囲むことはできません。
必須パラメーター¶
Amazon AWS API Gatewayの場合¶
統合名
API 統合の名前を指定します。この名前は オブジェクト識別子 のルールに従います。名前は、使用するアカウントの API 統合間において一意である必要があります。
プロバイダー情報
HTTPS プロキシサービスタイプを指定します。有効な値:
aws_api_gateway
: 地域のエンドポイントを使用するAmazon API Gatewayの場合。aws_private_api_gateway
: プライベートエンドポイントを使用するAmazon 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
セキュリティを最大化するには、許可される場所を実用範囲内においてできるだけ狭く制限する必要があります。
Microsoft Azure API Managementサービス¶
統合名
API 統合の名前を指定します。この名前は オブジェクト識別子 のルールに従います。名前は、使用するアカウントの API 統合間において一意である必要があります。
テナントID
すべてのAzure API Managementインスタンスが属するOffice 365テナントの ID を指定します。API 統合は1つのテナントのみを認証できるため、許可およびブロックされた場所は、すべてこのテナントに属する API Managementインスタンスを参照する必要があります。
テナント ID を見つけるには、Azureポータルにログインして Azure Active Directory » Properties をクリックします。テナント ID が Directory ID フィールドに表示されます。
AzureアプリケーションID
リモートサービス用Azure AD (Active Directory)アプリの「アプリケーション(クライアント)ID」。 Azureでカスタマイズ可能な外部関数の作成 の指示に従った場合、これは、それらの指示のワークシートに記録した「Azure Function App AD アプリケーション ID」です。
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
セキュリティを最大化するには、許可される場所を実用範囲内においてできるだけ狭く制限する必要があります。
オプションのパラメーター¶
これらのオプションのパラメータは両方に適用されます。
Amazon AWS API Gateway。
Azure API Managementサービス。
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 プロキシサービスを使用できます。
例¶
この例は、 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';