Premiers pas avec Snowflake REST APIs

Cette section décrit comment accéder à Snowflake REST APIs en utilisant Postman.

Créer un compte Postman et importer des collections Snowflake REST APIs

Note

Ces étapes ne sont fournies qu’à titre d’exemple, et, si vous suivez l’exemple, vous pourriez avoir besoin de droits supplémentaires sur des données, des produits ou des services tiers qui ne sont pas détenus ou fournis par Snowflake. Avant de poursuivre, assurez-vous de disposer des droits appropriés sur les données, produits ou services tiers.

Pour créer un compte et importer les collections :

  1. Téléchargez les collections d’API du référentiel Git dans un dossier.

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

  2. Ouvrez l’application Postman et créez un compte, si nécessaire.

  3. Dans Postman, ouvrez l’espace de travail souhaité.

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

  4. Sélectionnez Import.

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

  5. Sélectionnez folders.

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

  6. Dans la boîte de dialogue, sélectionnez le dossier dans lequel vous avez extrait la collection, puis sélectionnez Open.

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

  7. Vérifiez que tous les éléments sont sélectionnés et sélectionnez Import.

    Vous devriez voir les collections répertoriées dans le panneau de gauche, comme indiqué :

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

Spécifiez bearerToken dans Postman

Les demandes REST nécessitent un jeton JWT dans l’en-tête de la demande pour authentifier la demande. Dans Postman, vous pouvez copier le jeton JWT dans la propriété d’en-tête bearerToken, comme indiqué.

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

Vous pouvez ensuite définir la clé x-snowflake-authorization-token-type dans KEYPAIR_JWT dans chaque en-tête de demande, comme indiqué :

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

Note

Si vous préférez écrire des applications Python, vous pouvez utiliser l’API Snowflake Python pour gérer les objets Snowflake. Pour plus d’informations, voir Snowflake Python APIs : gestion des objets Snowflake avec Python.

Soumettez une demande

Pour soumettre une demande, vous pouvez envoyer une requête GET, POST ou PUT au point de terminaison souhaité :

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

Par exemple, pour soumettre une demande de création d’une tâche, vous devez créer une requête POST semblable à la suivante :

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

Ce qui suit montre comment vous pouvez obtenir une liste de tâches à l’aide de GET /api/v2/databases/database/schemas/schema/tasks dans Postman :

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

Gérer une réponse

Chacun des points de terminaison Snowflake REST APIs renvoie une réponse sous la forme JSON, semblable à ce qui suit :

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

Gérer une requête de longue durée (réponse 202)

Lorsque Snowflake accepte une requête dont l’exécution prend plus de 45 secondes, la demande renvoie un code de réponse 202. L’en-tête de réponse 202 comprend un paramètre Location qui fournit une URL relative similaire à ce qui suit que vous pouvez utiliser pour vérifier le statut de la demande en cours.

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

Vous pouvez créer une boucle dans votre code pour vérifier le statut jusqu’à ce que la demande renvoie un message 200. L’exemple de pseudo-code suivant illustre un flux que vous pourriez utiliser :

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

Pour la documentation de référence complète sur Snowflake REST APIs, voir Référence d’API Snowflake Result.

Gérer un résultat volumineux

En cas de réponse importante, le résultat complet est divisé en plusieurs pages. La première page de données (page 0) est renvoyée comme corps de réponse à la demande d’origine. Pour les pages restantes, les clients doivent utiliser des URLs dans l’en-tête Link pour les récupérer.

Exemple d’en-tête 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"

L’en-tête Link de l’exemple contient la première page, la page suivante et le chemin de la dernière page. L’en-tête pourrait également contenir un chemin rel="prev" vers la page précédente dans certaines situations.

Langage: Français