Snowflake REST APIs 入門

このセクションでは、Postmanを使って Snowflake REST APIs にアクセスする方法について説明します。

Postmanアカウントを作成し、 Snowflake REST APIs コレクションをインポートする

注釈

これらのステップはあくまで例として示したものです。例に従った場合、Snowflakeが所有または提供していないサードパーティのデータ、製品、またはサービスに対する追加の権利が必要になる場合があります。続行する前に、サードパーティのデータ、製品、またはサービスに対する適切な権利を持っていることを確認してください。

アカウントを作成し、コレクションをインポートするには。

  1. Gitリポジトリ から API コレクションをフォルダにダウンロードします。

    ../../_images/api-collections-git.png

  2. Postmanアプリケーションを開き、必要であればアカウントを作成します。

  3. Postmanで、目的のワークスペースを開きます。

    ../../_images/postman-workspace.png

  4. Import を選択します。

    ../../_images/postman-import-workspace.png

  5. folders を選択します。

    ../../_images/postman-download-collections.png

  6. ダイアログで、コレクションを抽出したフォルダを選択し、 Open を選択します。

    ../../_images/postman-import-elements.png

  7. すべての項目が選択されていることを確認し、 Import を選択します。

    左のパネルに図のようにコレクションが表示されているはずです。

    ../../_images/postman-verify-import.png

Postmanで bearerToken を指定する

REST リクエストは、リクエストを認証するためにリクエストヘッダーに JWT トークンを必要とします。Postmanでは、図のように JWT トークンを bearerToken ヘッダープロパティにコピーできます。

../../_images/postman-bearer-token.png

次に、各リクエストヘッダーで x-snowflake-authorization-token-type キーを KEYPAIR_JWT に設定します。

../../_images/postman-set-header.png

注釈

Python アプリケーションを書きたい場合は、Snowflake Python API を使用して Snowflake オブジェクトを管理できます。詳細については、 Snowflake Python APIs: PythonによるSnowflakeオブジェクトの管理 をご参照ください。

リクエストを送信する

リクエストを送信するには、 GET 、 POST 、 PUT のいずれかのリクエストを目的のエンドポイントに送信します。

POST /api/v2/databases/{database}/schemas/{schema}/tasks
(request body)
Copy

例えば、タスクを作成するリクエストを提出するには、以下のような POST リクエストを作成します。

def create_task(task_name, create_mode):
    """
    Create a task given the task name and create mode
    """
    headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + generate_JWT_token(),
    "Accept": "application/json",
    "User-Agent": "myApplicationName/1.0",
    "X-Snowflake-Authorization-Token-Type": "KEYPAIR_JWT"
    }
    request_body = {
        "name": task_name,
        "warehouse": "myWarehouse",
        "definition": "select 1"
    }
    request_url = "{}/api/v2/databases/{}/schemas/{}/tasks?createMode={}".format(SNOWFLAKE_URL, DATABASE_NAME, SCHEMA_NAME, create_mode)
    response = requests.post(request_url, json=request_body, headers=headers, timeout=60)
    print_response("POST {}".format(request_url), response)
Copy

以下はPostmanの GET /api/v2/databases/database/schemas/schema/tasks を使ってタスクのリストを取得する方法を示しています。

../../_images/postman-list-tasks.png

応答を処理する

Snowflake REST APIs の各エンドポイントは、以下のような応答を JSON として返します。

{
  [
      {
          "name": "name_example",
          "warehouse": "test_wh",
          "schedule": {
          "schedule_type": "MINUTES_TYPE",
          "minutes": 10
          },
          "comment": "test_comment",
          "config": {
          "output_dir": "/temp/test_directory/",
          "learning_rate": "0.1"
          },
          "definition": "this task does...",
          "predecessors": [
          "task1",
          "task2",
          "task3"
          ],
          "user_task_managed_initial_warehouse_size": "XSMALL",
          "user_task_timeout_ms": 10,
          "suspend_task_after_num_failures": 3,
          "condition": "select 1",
          "allow_overlapping_execution": false,
          "error_integration": "my_notification_int",
          "created_on": "2024-06-18T01:01:01.111111",
          "id": "task_id",
          "owner": "TASK_ADMIN",
          "owner_role_type": "ADMIN",
          "state": "started",
          "last_committed_on": "2024-06-18T01:01:01.111111",
          "last_suspended_on": "2024-06-18T01:01:01.111111",
          "database_name": "TESTDB",
          "schema_name": "TESTSCHEMA"
      }
  ]
}
Copy

長いリクエストを処理する (202 レスポンス)

Snowflakeが完了までに45秒以上かかるリクエストを受け付けると、リクエストは202応答コードを返します。202応答ヘッダーは、進行中のリクエストのステータスを確認するために使用できる、以下のような相対 URL を提供する Location パラメータを含みます。

Location: /api/v2/results/5b3ce6ae-d123-4c27-afb3-8a26422d5f321
Copy

リクエストから200メッセージが返されるまで、ステータスをチェックするループをコード内に作ることができます。以下の擬似コード・サンプルは、使用可能なフローを示しています。

location = <content of the Location header>

while TRUE {
    sleep for x milliseconds
    response = call GET ( host + location )

    if response is 202
      continue

    if response = 200 {
        <code to extract data from the response header>
        exit
    }
}

完全な Snowflake REST APIs リファレンス・ドキュメントは、 Snowflake Result API reference をご参照ください。

大きな結果を処理する

大きなレスポンスの場合、完全な結果は複数のページに分割されます。データの最初のページ（ページ0）は、オリジナルリクエストに対するレスポンスボディとして返されます。残りのページについては、クライアントは:codenowrap:Link ヘッダーのURLs を使って取得する必要があります。

サンプル:codenowrap:Link ヘッダー:

Link: </api/v2/results/01b66701-0000-001c-0000-0030000b91521?page=0>; rel="first",</api/v2/results/01b66701-0000-001c-0000-0030000b91521?page=1>; rel="next",</api/v2/results/01b66701-0000-001c-0000-0030000b91521?page=9>; rel="last"

この例の:codenowrap:Link ヘッダーには、最初のページ、次のページ、最後のページのパスが含まれています。ヘッダーはまた、状況によっては:codenowrap:rel="prev" 前ページのパスを含むこともできます。

言語: 日本語