Snowflake REST APIs 시작하기¶

이 섹션에서는 Postman을 사용하여 Snowflake REST APIs 에 액세스하는 방법에 대해 설명합니다.

Postman 계정 만들기 및 Snowflake REST APIs 컬렉션 가져오기¶

참고

이러한 단계는 예시로만 보여주는 것이며, 예시를 따라 실습하려면 Snowflake가 소유하거나 제공하지 않는 서드 파티 데이터, 제품 또는 서비스에 대한 권한이 추가로 필요할 수 있습니다. 계속하기 전에 서드 파티 데이터, 제품 또는 서비스에 대한 적절한 권리가 있는지 확인하십시오.

계정을 생성하고 컬렉션을 가져오려면:

API 컬렉션을 Git 리포지토리 에서 폴더로 다운로드합니다.
Postman 애플리케이션을 열고, 필요한 경우 계정을 생성합니다.
Postman에서 원하는 작업 영역을 엽니다.
Import 를 선택합니다.
folders 를 선택합니다.
대화 상자에서 컬렉션을 추출한 폴더를 선택하고 Open 을 선택합니다.
모든 항목이 선택되었는지 확인하고 Import 를 선택합니다.

다음과 같이 왼쪽 패널에 컬렉션이 나열되어야 합니다.

Postman에서 `bearerToken` 지정¶

REST 요청은 요청 헤더에 JWT 토큰이 있어야 요청을 인증할 수 있습니다. Postman에서는 다음과 같이 JWT 토큰을 bearerToken 헤더 속성에 복사할 수 있습니다.

참고

Python 애플리케이션을 작성하는 것을 선호하는 경우 Snowflake Python API를 사용하여 Snowflake 오브젝트를 관리할 수 있습니다. 자세한 내용은 Snowflake Python APIs: Python으로 Snowflake 오브젝트 관리하기 섹션을 참조하십시오.

요청 제출¶

요청을 제출하려면 원하는 엔드포인트에 GET, POST 또는 PUT 요청을 보내면 됩니다.

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

예를 들어 작업 생성 요청을 제출하려면 다음과 유사한 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"
    }
    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)

다음은 Postman에서 GET /api/v2/databases/database/schemas/schema/tasks 를 사용하여 작업 목록을 가져오는 방법을 보여줍니다.

응답 처리¶

각 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"
      }
  ]
}

장기 실행 요청 처리(202 응답)¶

Snowflake가 완료하는 데 45초 이상 걸리는 요청을 수락하면 해당 요청은 202 응답 코드를 반환합니다. 202 응답 헤더에는 진행 중인 요청의 상태를 확인하는 데 사용할 수 있는 다음과 유사한 상대 URL을 제공하는 Location 매개 변수가 포함되어 있습니다.

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

사용자는 요청이 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 참조 섹션을 참조하십시오.

대규모 결과 처리¶

응답이 많은 경우 전체 결과가 여러 페이지로 나뉩니다. 첫 번째 데이터 페이지(페이지 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" 경로를 포함할 수도 있습니다.