Erste Schritte mit dem Snowflake REST APIs

In diesem Abschnitt wird beschrieben, wie Sie mit Postman auf Snowflake REST APIs zugreifen können.

Erstellen Sie ein Postman-Konto und importieren Sie Snowflake REST APIs-Sammlungen

Bemerkung

Die folgenden Schritte werden nur als Beispiel dargestellt. Wenn Sie dem Beispiel folgen, benötigen Sie möglicherweise zusätzliche Rechte für Daten, Produkte oder Dienste von Drittanbietern, die nicht im Besitz von Snowflake sind oder von Snowflake bereitgestellt werden. Vergewissern Sie sich, dass Sie über die entsprechenden Rechte für Daten, Produkte oder Dienstleistungen Dritter verfügen, bevor Sie fortfahren.

So erstellen Sie ein Konto und importieren die Sammlungen:

  1. Laden Sie die Sammlungen API aus dem Git-Repository https://github.com/snowflakedb/snowflake-rest-api-specs/tree/main/public-preview/8.30/collection in einen Ordner herunter.

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

  2. Öffnen Sie die Postman-Anwendung und erstellen Sie, falls erforderlich, ein Konto.

  3. Öffnen Sie in Postman den gewünschten Arbeitsbereich.

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

  4. Wählen Sie Import aus.

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

  5. Wählen Sie folders aus.

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

  6. Wählen Sie im Dialogfeld den Ordner, in den Sie die Sammlung extrahiert haben, und wählen Sie Open.

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

  7. Vergewissern Sie sich, dass alle Elemente ausgewählt sind, und wählen Sie Import.

    Sie sollten die Auflistung der Sammlungen im linken Bereich sehen, wie in der Abbildung dargestellt:

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

Geben Sie die bearerToken in Postman an

REST-Anfragen benötigen ein JWT-Token im Anfrage-Header, um die Anfrage zu authentifizieren. In Postman können Sie das JWT-Token in die bearerToken-Header-Eigenschaft kopieren, wie gezeigt.

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

Sie können dann den x-snowflake-authorization-token-type-Schlüssel in jedem Anfrage-Header auf KEYPAIR_JWT einstellen, wie gezeigt:

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

Bemerkung

Wenn Sie lieber Python-Anwendungen schreiben, können Sie die Snowflake Python-API verwenden, um Snowflake-Objekte zu verwalten. Weitere Informationen dazu finden Sie unter Snowflake Python APIs: Verwalten von Snowflake-Objekten mit Python.

Eine Anfrage senden

Um eine Anfrage zu stellen, können Sie eine GET, POST oder PUT Anfrage an den gewünschten Endpunkt senden:

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

Um beispielsweise eine Anfrage zur Erstellung einer Aufgabe zu stellen, würden Sie eine POST-Anfrage ähnlich der folgenden erstellen:

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

Im Folgenden wird gezeigt, wie Sie mit GET /api/v2/databases/database/schemas/schema/tasks in Postman eine Auflistung der Aufgaben erhalten:

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

Eine Antwort bearbeiten

Jeder der Endpunkte von Snowflake REST APIs gibt eine Antwort als JSON zurück, ähnlich der Folgenden:

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

Bearbeiten Sie eine langlaufende Anfrage (202 Antwort)

Wenn Snowflake eine Anfrage annimmt, deren Bearbeitung länger als 45 Sekunden dauert, gibt die Anfrage einen Antwortcode 202 zurück. Der Header der Antwort 202 enthält einen Parameter Location, der einen relativen URL ähnlich dem folgenden liefert, mit dem Sie den Status der laufenden Anfrage überprüfen können.

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

Sie können eine Schleife in Ihrem Code erstellen, um den Status zu überprüfen, bis die Anfrage eine 200 Meldung zurückgibt. Das folgende Beispiel für Pseudocode veranschaulicht den Ablauf, den Sie verwenden könnten:

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

Die vollständige Snowflake REST APIs-Referenzdokumentation finden Sie unter Snowflake Ergebnis API-Referenz.

Verarbeiten Sie ein großes Ergebnis

Im Falle einer umfangreichen Antwort wird das vollständige Ergebnis auf mehrere Seiten aufgeteilt. Die erste Seite der Daten (Seite 0) wird als Antwort Body auf die ursprüngliche Anfrage zurückgegeben. Für die übrigen Seiten müssen Clients den URLs im Link-Header verwenden, um sie abzurufen.

Beispiel Link-Header:

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"

Der Link-Header im Beispiel enthält den Pfad der ersten Seite, der nächsten Seite und der letzten Seite. Der Header könnte in manchen Situationen auch einen rel="prev"-Pfad für die vorherige Seite enthalten.

Sprache: Deutsch