„Call API“-Tool konfigurieren

Diese Einrichtung erfordert API- und Programmierkenntnisse.

Mit dem „Call API“-Tool können Sie öffentliche API-Aufrufe verwalten, die Sie in Ihren Automatisierungs-Workflows in Smartsheet Bridge ausführen. Es besteht aus zwei Hauptkomponenten:

• Profiles – Speichert Informationen zu den System-APIs, mit denen Sie Ihre Workflows verbinden möchten. 

• „Make API Call“-Modul – Verwendet Profildaten und spezifische Details, die Sie angeben, um einen API-Aufruf an eine System-API auszuführen.

   

Entwicklungstipp für Smartsheet Bridge

Profile erleichtern auch das Ändern von Workflows mithilfe dieses Profils, wenn sich Schlüsselinformationen ändern, z. B. Ihr Autorisierungstoken oder die „Base URL“. Durch eine Aktualisierung des Profils wird sichergestellt, dass alle Module, die das Profil aufrufen, die neuesten Daten für den Aufruf erhalten.

API-Aufrufe – Felder

Bevor wir beginnen, gehen wir einige terminologische Details zur Verwendung von APIs durch.

Base URL

Dieses Feld ist im Profil enthalten und ist der Teil der API-URL, der immer gleich bleibt. Für Smartsheet verwenden Sie die „Base URL“: https://api.smartsheet.com/2.0/

Endpoint

Dieses Feld ist im „Make API Call“-Modul enthalten und gibt die Aktion an, die Sie ausführen möchten (z. B. das Sheet sortieren). In diesem Wert können Sie alle Datenverweise hinzufügen, die Sie von Ihren Smartsheet Bridge-Auslösern benötigen.

Hier sind Beispiele zum Einrichten statischer oder dynamischer Daten:

• Statischer ID-Wert – Das ist das URL-Format für diesen Datentyp: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Sie müssen die Sheet-ID in dieser URL angeben, damit der API-Aufruf immer genau dieses Sheet sortiert. 
• Dynamischer „Run Log“-Datenverweis – Das URL-Format für diese Daten ähnelt dem des statischen ID-Werts: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Doch anstatt die Sheet-ID hinzuzufügen, müssen Sie den Sheetdatenverweis aus dem „Run Log“ des Smartsheet Bridge-Workflows hinzufügen. Das ist nützlich, wenn Ihr Smartsheet Bridge-Workflow bei Änderungen ausgelöst wird oder Daten aus mehreren Sheets abruft. Wenn Sie diesen URL-Typ verwenden, sortiert der API-Aufruf das Sheet, das in dieser URL angegeben ist.

Method

„Method“ definiert die Art der Vorgänge, die Sie ausführen möchten, und Sie richten dieses Feld für jeden API-Aufruf im „Make API Call“-Modul ein. Die meisten APIs beschreiben die erforderliche Methode für einen bestimmten API-Endpunkt. Bei Smartsheet verwenden Sie beispielsweise die folgenden Methoden:

• GET: Bringt Daten in Ihren Smartsheet Bridge-Workflow, indem eine Zeile aus einem Sheet abgerufen wird.
• POST: Erstellt etwas. Sie können z. B. eine Zeile zu einem Sheet hinzufügen.
• PUT: Aktualisiert etwas. Sie können z. B. eine Zeile in einem Sheet aktualisieren.
• DELETE: Löscht etwas. Sie können z. B. eine Zeile aus einem Sheet löschen.

Headers

„Headers“ sind die Werte, die Sie für die Anforderung benötigen, und die Schlüssel-Wert-Paare. Sie werden meistens verwendet, um die Autorisierung (Berechtigungen) zu verwalten. In Smartsheet-Aufrufen haben Sie z. B. einen Schlüssel-Header namens „Authorization“, dessen Wert auf Bearer [Ihr API-Token eingeben] festgelegt ist.

Headers, die für jeden Aufruf bei einem System erforderlich sind, können im Profil eingerichtet werden. Zusätzliche Header für bestimmte Aktionen können im „Make API Call“-Modul in Ihrem Workflow eingerichtet werden. 
 

Form Parameters 

„Form Parameters“ werden auch als Abfrageparameter oder Argumente bezeichnet. Sie sind zusätzliche Elemente, die Sie in der Anforderung definieren können. Sie legen diese im „Make API Call“-Modul fest.

Ein Beispielszenario wäre das Anwenden einer Seitenangabe bei Smartsheet-Aufrufen, sodass nur eine bestimmte Anzahl von Elementen in der Antwort enthalten ist. Zum Beispiel, wenn Sie nur die erste Seite eines Berichts mit 20.000 Zeilen abrufen möchten.
 

Body

Ein „Body“ enthält die relevanten Anforderungsdetails, die Sie senden müssen. Er ist normalerweise im JSON-Format.

Wenn „Form Parameters“ gesendet werden, werden die Daten von Body überschrieben.

In einem Sort Sheet-API-Aufruf würde ein „Body“ wie folgt aussehen: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. Der „Body“ im obigen Beispiel kann einen der folgenden Werttypen verwenden:

• Statischer Wert für eine bestimmte Spalte in einem Sheet oder
• Dynamischer „Run Log“-Datenverweis, bei dem die Spalten-ID angezeigt wird. 

Je nach Art der gesendeten Anforderung ist ein „Body“ eventuell nicht erforderlich. Beispielsweise benötigen Sie keinen „Body“ für GET-Anrufe.
 

Zurückgegebene Daten

Wenn die antwortende API ein JSON-Objekt zurücksendet, wird es im „Run Log“ gespeichert. Dadurch können Sie in späteren Teilen des Workflows auf die zurückgegebenen Daten verweisen.

Jetzt kennen Sie die Felder beim Einrichten der „Call API“-Profile und „Make API Call“-Module. Lesen Sie weiter, um mehr über die Einrichtung und Verwendung dieses Dienstprogramms zu erfahren.

Voraussetzungen für erste Schritte

• Ein Sheet 
  • Die Sheet-ID
  • Eine Spalte, für die bei einer Änderung in Ihren Zeilen Ihr Smartsheet Bridge-Workflow ausgelöst werden soll
• Smartsheet Bridge
  • Smartsheet-Integration
  • Smartsheet Bridge-Workflow-Auslöser: Smartsheet – When Column Values are Changed
  • Smartsheet Bridge-Workflow-Module: Make API Call
• Ein Smartsheet-API-Schlüssel. Hier erfahren Sie, wie Sie einen API-Schlüssel für Smartsheet generieren. 

Erste Schritte

Um diesen Workflow in Smartsheet Bridge zu erstellen, authentifizieren Sie die Smartsheet-Integration für Ihren Smartsheet Bridge-Arbeitsbereich. Lesen Sie die Schritte zum Einrichten der Smartsheet-Integration für Smartsheet Bridge. 

Lassen Sie beim Erstellen Ihres Workflows Ihr Sheet, die Smartsheet-API-Dokumentation und Ihren Smartsheet Bridge-Workflow auf drei separaten Tabs geöffnet. Das erleichtert die Navigation beim Erstellungsprozess.

Schritt 1: Erstellen des grundlegenden Workflow-Modells

Rufen Sie zunächst alle Module ab, die Sie für den Workflow benötigen. 

1. Erstellen Sie einen neuen Workflow in Smartsheet Bridge. 
2. Verwenden Sie im Workflow-Generator den Bereich zum Hinzufügen des „Make API Call“-Moduls.
3. Speichern Sie den Workflow.

Das sollte in Ihrem Workflow angezeigt werden, wenn Sie fertig sind:

Brandfolder Image

Einrichten des Workflow-Auslösers

Nachdem Sie das grundlegende Workflow-Modell erstellt haben, beginnen Sie mit der Einrichtung des Workflow-Auslösers.

1. Wählen Sie das Modul Trigger aus.
2. Um den Bereich Integration in einem neuen Tab zu öffnen, wählen Sie im Abschnitt Integrations die Integrations Page aus.

3. Suchen Sie Smartsheet in der Integrationsliste.
    

   Sie können die Option Connected unter dem Smartsheet Bridge-Logo verwenden, um eine Liste zu erhalten, die nur die Integrationen enthält, die für diesen Arbeitsbereich authentifiziert wurden.

4. Erweitern Sie die Zeile Trigger.
5. Um einen neuen Auslöser zu erstellen, wählen Sie das Plus-Symbol aus.
6. Füllen Sie die folgenden Felder aus:
   • Trigger Name: Erstellen Sie eine benutzerdefinierte Beschriftung für Ihren Auslöser.
   • Sheet ID: Fügen Sie die Sheet-ID Ihres Sheets ein (das Sheet, das Sie sortieren möchten).
   • Event Type: Wählen Sie When Column Values are Changed aus. 
   • Column Name or ID: Geben Sie den Namen der Smartsheet-Spalte ein, auf die Sie antworten möchten. Wenn Sie z. B. die Zeilen auf dem Sheet jedes Mal sortieren möchten, wenn sich die Priorität ändert, geben Sie den Namen Ihrer Prioritätsspalte ein.
   • Select Workflow: Wählen Sie den neuen Workflow, den Sie gerade erstellt haben, aus der Dropdown-Liste aus.
7. Wählen Sie Save aus.
8. Kopieren Sie die Spalten-ID in der Trigger-Info.
   • Die Spalten-ID ist in der „Trigger“-Info verfügbar, wenn Sie den Workflow-Auslöser speichern.
9. Fügen Sie sie in den Editor oder ein beliebiges Textverarbeitungsprogramm ein. Sie benötigen die Spalten-ID für einen späteren Schritt. 

10. Kehren Sie zu Ihrem Workflow zurück.
     

    Wenn Sie zum ursprünglichen Tab zurückkehren möchten, aktualisieren Sie die Seite, um den Auslöser anzuzeigen.

Abrufen der API-Aufrufdetails

Wertänderungen in der Prioritätsspalte Ihres Sheets werden in diesem Workflow ausgelöst. Sobald dieser Workflow den/die Auslöser erkennt, führt er die erforderlichen Aktionen für das jeweilige Sheet aus. Um die Smartsheet-Module aufzufüllen, verwenden wir daher die Verweise auf die Laufzeitdaten (Run Log) des Auslösers.

Für diesen Workflow führen Sie einen API-Aufruf an den Endpunkt Smartsheet Sort Sheet aus. Verwenden Sie die Smartsheet-API-Dokumentation, um das Beispiel in cURL zu ändern.

Schritt 2: Einrichten Ihres ersten Profils

Profile speichern Schlüsselinformationen für die System-APIs, mit denen Sie Ihre Workflows verbinden möchten. Wenn Sie ein Profil im „Make API Call“-Modul auswählen, werden einige der erforderlichen Informationen für den API-Aufruf bereits eingerichtet sein. 

1. Melden Sie sich bei Ihrem Smartsheet Bridge-Konto an.
2. Öffnen Sie den Tab Integrations.
3. Wählen Sie das Dienstprogramm Call API aus.

4. Wählen Sie Add to Profiles aus.

   Brandfolder Image

   
5. Benennen Sie Ihr Profil. Jeder Profilname muss eindeutig sein.
6. Fügen Sie die „Base URL“ für die System-API hinzu, mit der Sie eine Verbindung herstellen möchten.
   • In diesem Beispiel ist die „Base URL“ für Smartsheet: https://api.smartsheet.com/2.0/
7. Fügen Sie unter Secret Headers alle Header hinzu, die Token oder Schlüsselinformationen enthalten (z. B. API-Token).
   • In Smartsheet-Aufrufen gibt es z. B. normalerweise einen Schlüssel-Header namens Authorization, dessen Wert auf Bearer [Ihr API-Token eingeben] festgelegt ist.
8. Fügen Sie unter Headers alle Header hinzu, die in allen API-Aufrufen enthalten sein sollen, die Sie mit diesem Profil ausführen.
   • In diesem Beispiel haben wir Content-Type als Header mit dem Wert application/json verwendet.
9. Speichern Sie das Profil.

10. Kehren Sie zu Ihrem Workflow zurück.

     

Entwicklungstipp für Smartsheet Bridge

Die „Base URL“ ist der Teil der URL von der System-API, der immer gleich bleibt, unabhängig davon, was Sie in diesem System bewirken möchten. Der „Endpoint“ im „Make API Call“-Modul dient dazu, die spezifischen Details und die spezifische Aktion anzugeben, die Sie mit diesem API-Aufruf ausführen möchten.

Beispiel: Wir verwenden die Smartsheet-API, um ein Sheet zu sortieren. Die „Base URL“ für unser Smartsheet-API-Profil ist https://api.smartsheet.com/2.0 und die spezifische Aktion, die wir mit dem Modul ausführen, ist das Sortieren eines bestimmten Sheets. Deshalb fügen wir sheets/sheet_id_or_data_reference_here/sort in das Feld Endpoint des Moduls ein.

Schritt 3: Einrichten des „Make API Call“-Moduls in Ihrem Workflow

1. Wählen Sie im „Make API Call“-Modul das gewünschte Profil aus der Dropdown-Liste aus.
2. Fügen Sie im Feld Endpoint den Teil des URL-Felds ein, der nicht zum Feld Base URL im Profil hinzugefügt wurde.
   • In diesem Beispiel haben wir „sheets/sheet_id_or_data_reference_here/sort“ verwendet.
3. Füllen Sie die folgenden Felder aus. Beachten Sie, dass Sie nicht alle verwenden müssen:
   • Legen Sie Method auf POST fest.
   • Im Feld HTTP Request Body würde ein Inhalt wie folgt aussehen: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Form Parameters (falls erforderlich – nicht für diesen Workflow)

4. Speichern Sie die Änderungen.

   Brandfolder Image

   

   
    

Schritt 4: Testen des Workflows

1. Öffnen Sie Ihr Sheet. 
2. Ändern Sie einen Wert in Ihrer Prioritätsspalte. 
3. Speichern Sie das Sheet. 

Wenn Ihre Prioritätsspalte eine Dropdown-Liste ist, werden die Zeilen (je nach Ihrer Konfiguration im „Body“ des API-Aufrufs) in auf- oder absteigender Reihenfolge der Werte sortiert, wie sie in den Spalteneinstellungen angezeigt werden. 

Zusätzliche Einstellungen für das Modul

• Das „Make API Call“-Modul gibt alle API-Aufrufe als JSON-Objekt zurück. Wenn die Antwort als Zeichenfolge zurückgegeben werden soll, aktivieren Sie das Kontrollkästchen Return raw response unter Additional settings im Modul.
• Wenn Sie zusätzliche Header für einen bestimmten Aufruf einfügen müssen, kopieren Sie sie in den Abschnitt HTTP Request Headers.

Alternative Optionen für diesen Workflow

Hier sind einige Ideen, wie Sie diesen Workflow individuell anpassen können:

• Lösen Sie den Workflow aus anderen Sheets oder Spalten als den zu sortierenden aus. Dazu müssen Sie die Details von „API Call“ an das Sheet und die Spalte anpassen, die Sie sortieren möchten. 
• Fügen Sie eine Bedingung zu Ihrer Sortierung hinzu. Verwenden Sie nach dem Auslösen des Workflows das Modul Junction, um den Spaltenwert zu überprüfen und verschiedene Aktionen basierend auf den Änderungen an der Prioritätsspalte auszuführen (z. B. bei Priorität 0 die Zeile aus dem Sheet verschieben und bei Priorität 1 das Sheet sortieren).
• Verwenden Sie einen Zeitplanauslöser. Wenn Sie diesen Auslöser verwenden, müssen Sie überhaupt nicht auf Änderungen reagieren, da das Sheet einmal pro Tag, Woche oder Monat sortiert wird.

Verwenden der Call API-Tools in Ihren Lösungen

• Profile gelten für den Arbeitsbereich, deshalb können alle Workflows in Ihrem Arbeitsbereich das gleiche Profil in allen verwendeten „Make API Call“-Modulen nutzen. Wenn Profildetails geändert werden müssen, weil sich die Berechtigungen eines Benutzers geändert haben oder die System-API Änderungen vornimmt, gibt es einen zentralen Ort, an dem diese Anpassungen vorgenommen und auf Workflows im Arbeitsbereich angewandt werden können, die dieses Profil verwenden.
• Für jede zusätzliche System-API, mit der Sie eine Verbindung herstellen müssen, können Sie ein neues eindeutiges Profil einrichten, indem Sie dem ersten Teil der Anleitung folgen.