Introdução ao Snowflake REST APIs

Esta seção descreve como acessar o Snowflake REST APIs usando o Postman.

Crie uma conta Postman e importe as coleções do Snowflake REST APIs

Nota

Essas etapas são mostradas apenas como um exemplo e segui-las pode exigir direitos adicionais em dados, produtos ou serviços de terceiros que não são de propriedade ou fornecidos pela Snowflake. Certifique-se de ter os direitos apropriados sobre dados, produtos ou serviços de terceiros antes de continuar.

Para criar uma conta e importar as coleções:

  1. Baixe as coleções de API do repositório Git para uma pasta.

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

  2. Abra o aplicativo Postman e crie uma conta, se necessário.

  3. No Postman, abra o espaço de trabalho desejado.

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

  4. Selecione Import.

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

  5. Selecione folders.

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

  6. Na caixa de diálogo, selecione a pasta de onde você extraiu a coleção e selecione Open.

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

  7. Verifique se todos os itens estão selecionados e selecione Import.

    Você deverá ver as coleções listadas no painel esquerdo, conforme mostrado:

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

Especifique o bearerToken no Postman

As solicitações REST exigem um token JWT no cabeçalho da solicitação para autenticá-la. No Postman, é possível copiar o token JWT para a propriedade do cabeçalho bearerToken, conforme mostrado.

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

Nota

Se preferir escrever aplicativos Python, é possível usar a API Snowflake Python para gerenciar objetos Snowflake. Para obter mais informações, consulte Snowflake Python APIs: Gerenciamento de objetos Snowflake com Python.

Como enviar uma solicitação

Para enviar uma solicitação, é necessário enviar uma solicitação GET, POST ou PUT para o ponto de extremidade desejado:

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

Por exemplo, para enviar uma solicitação para criar uma tarefa, é possível criar uma solicitação POST semelhante à seguinte:

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)

A seguir mostramos como você pode obter uma lista de tarefas usando GET /api/v2/databases/database/schemas/schema/tasks no Postman:

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

Como lidar com uma resposta

Cada um dos pontos de extremidade do Snowflake REST APIs retorna uma resposta como JSON, semelhante à seguinte:

{
  [
      {
          "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"
      }
  ]
}

Como lidar com uma solicitação de longa duração (resposta 202)

Quando o Snowflake aceita uma solicitação que leva mais de 45 segundos para ser concluída, a solicitação retorna um código de resposta 202. O cabeçalho de resposta 202 inclui um parâmetro Location que fornece um URL relativo semelhante ao seguinte que você pode usar para verificar o status da solicitação em andamento.

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

É possível criar um loop no seu código para verificar o status até que a solicitação retorne uma mensagem 200. O amostra de pseudocódigo a seguir ilustra um fluxo que você pode usar:

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
    }
}

Para obter a documentação de referência completa do Snowflake REST APIs, consulte a Referência da API de resultados do Snowflake.

Como lidar com um resultado grande

No caso de uma resposta grande, o resultado completo é dividido em várias páginas. A primeira página de dados (página 0) é retornada como um corpo de resposta à solicitação original. Para as páginas restantes, os clientes precisam usar URLs no cabeçalho de link para buscá-las.

Amostra do cabeçalho de 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"

O cabeçalho do link no exemplo contém o caminho da primeira página, da próxima página e da última página. O cabeçalho também pode conter um caminho rel="prev" para a página anterior em algumas situações.