Snowflake REST APIs でSnowflakeコンテキストを指定する

Snowflake REST APIs にリクエストを行うときに、Snowflakeコンテキストの側面を指定できます。

リクエストヘッダーを使用して、RESTAPI 呼び出しのコンテキストで次を指定できます。

  • X-Snowflake-Role ヘッダーでリクエストを承認するために使用されるSnowflakeのロール。

  • X-Snowflake-Warehouse ヘッダーでリクエストの実行に使用されるSnowflakeウェアハウス。

ユーザーのデフォルト設定に依存する代わりに、これらのヘッダーは各呼び出しを明示的、分離、および監査可能にします。各リクエストが、コンテキストを設定する追加の API 呼び出しを必要とせずに正しいロールとウェアハウスを使用することを保証します。

RESTAPI リクエスを作成するときにコンテキストを指定することにより、以下のタスクを達成できます。

  • ステートレスの呼び出しを実行します。

    最初にセッションコンテキストを設定するために別の API 呼び出しを必要とせずに、呼び出しが特定のロールを使用することを保証します。

  • ユーザーの変更は避けてください。

    ALTERUSER ... SETDEFAULT_ROLE=...を実行する代わりに、リクエストごとにロールを安全に切り替えます。これは時間がかかり、そのユーザーの他のすべてのセッションに影響します。

  • オンデマンドコンピューティングを有効にします。

    X-Snowflake-Warehouse ヘッダーを指定するだけで、デフォルトのウェアハウスのないユーザーまたはサービスアカウントがクエリを実行したり、プロシージャを作成したりできるようにします。

  • ユーザー管理を簡素化します。

    複数のロールを付与された1つのサービスユーザーを使用します---例: READER および WRITERその後、アプリケーションは X-Snowflake-Role ヘッダーを送信して、適切なタスクに対する適切な権限を選択します。この方法で、複数の単一ロールユーザーの管理を回避できます。

優先順位

ヘッダーが提供されると、ユーザーのデフォルト設定よりも次の順序で優先されます。

  1. ヘッダー（提供されている場合）が使用されます。

  2. それ以外の場合は、セッションの既定のロールまたは既定のウェアハウスが使用されます。

  3. どちらも必要な場合に利用できない場合は、呼び出しは失敗します。

リクエストを承認するときに使用するロールを指定する

X-Snowflake-Role ヘッダーを使用すると、リクエストを承認するときに使用するロールを指定できます。

要件

  • 指定するロールが存在し、ユーザーに付与され、使用中の認証方式で許可されている必要があります。

  • プログラムのアクセストークン（PAT） を使用する場合、リクエストされたロールは PAT の ROLE_RESTRICTION 内にある必要があります。PAT で許可されているよりも権限の高いロールを指定した場合、ユーザーに指定されたロールが付与されていた場合でも、リクエストは失敗します。

例

次の例では、ユーザーのデフォルトのロールに関係なく、承認に ACCOUNTADMIN を使用してデータベースを作成します。

X-Snowflake-Role ヘッダーの値は、二重引用符で囲むか、引用符なしで囲みます。

curl -X POST "$API_BASE/database/databases" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -d '{"name": "HDR_DEMO_DB", "comment": "Created via REST with role header"}'
Copy

ステートメントを実行するウェアハウスを指定します

X-Snowflake-Warehouse ヘッダーを使用すると、ステートメントの実行時に使用するウェアハウスを指定できます。このようなステートメントには、プロシージャの実行、Python関数の作成、コンピューティングリソースを必要とするクエリの実行などがあります。

要件

  • 有効なロールには、ウェアハウスに対する USAGE 権限が必要です。

  • デフォルトのウェアハウスが設定されておらず、このヘッダーを省略すると、ウェアハウスに依存する呼び出しは失敗します。

例

次の例では、BUILD_WH ウェアハウスを使用するPythonプロシージャを作成します。ロールには、ウェアハウスに対する USAGE 権限が必要です。作成された PYTHON_WH_TEST プロシージャはアクティブなウェアハウス名を返します。

X-Snowflake-Warehouse ヘッダーの値は、二重引用符で囲むか、引用符なしで囲みます。

curl -X POST "$API_BASE/procedure/databases/TEST_DB/schemas/TEST_SCHEMA/procedures" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Snowflake-Role: ACCOUNTADMIN" \
  -H "X-Snowflake-Warehouse: BUILD_WH" \
  -d '{
        "name": "PYTHON_WH_TEST",
        "arguments": [],
        "return_type": {"datatype": "VARIANT", "nullable": true},
        "language_config": {
          "python_function": {
            "handler":"main",
            "runtime_version":"3.11",
            "packages":["snowflake-snowpark-python"]
          }
        },
        "body": "def main(session):\n    return {\"warehouse\": session.get_current_warehouse()}"
      }'
Copy
言語: 日本語