Snowflake REST APIs 入门

本部分介绍如何使用 Postman 访问 Snowflake REST APIs。

创建 Postman 账户并导入 Snowflake REST APIs 集合

备注

这些步骤仅作为示例显示，按照示例操作可能需要对非 Snowflake 拥有或提供的第三方数据、产品或服务具有额外的权利。在继续操作前，请确保您对第三方数据、产品或服务拥有适当的权利。

要创建账户并导入集合，请执行以下操作：

  1. 从 Git 存储库 (https://github.com/snowflakedb/snowflake-rest-api-specs/tree/main/releases/8.40/collections) 将 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 响应标头包括一个 Location 参数，该参数提供了类似下面这样的相对 URL，您可以使用它来检查正在执行的请求的状态。

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 结果 API 参考。

处理大型结果

对于大型响应，完成的结果会划分到多个页面中。数据的第一页（第 0 页）作为原始请求的响应主体返回。对于剩余页面，客户端需要使用 Link 标头中的 URLs 来提取它们。

示例 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"

示例中的 Link 标头包含第一页、下一页和最后一页的路径。在某些情况下，标头还可以包含上一页的 rel="prev" 路径。

语言: 中文