Bridge-Dienstprogramme: API aufrufen

Das Call API-Dienstprogramm ermöglicht es Ihnen, öffentliche API-Aufrufe zu verwalten, die Sie in Ihren Automatisierungs-Workflows in Bridge durchführen. Es besteht aus zwei Hauptkomponenten: 

• Profile: speichern Informationen zu den System-APIs, mit denen Sie Ihre Workflows verbinden möchten. 

• Das Modul API aufrufen verwendet Profildaten und spezifische Details, die Sie angeben, um einen API-Aufruf an eine System-API auszuführen.

  Diese Einrichtung erfordert API- und Programmierkenntnisse.

Entwicklungstipp für Smartsheet Bridge

Profile vereinfachen Workflow-Änderungen, falls sich wichtige Informationen ändern, wie Ihr Autorisierungstoken oder die Basis-URL. Durch eine Aktualisierung des Profils wird sichergestellt, dass alle Module, die das Profil aufrufen, die neuesten Daten für den Aufruf erhalten.

„Make API Call“-Modul 

Dies ist das einzige Modul im Dienstprogramm und enthält die folgenden Felder:

Endpunkt

Dieses Feld gibt die Aktion an, die Sie durchführen möchten (zum Beispiel das Sheet sortieren). In diesem Wert können Sie alle Datenverweise von Ihren Smartsheet Bridge-Auslösern hinzufügen. Hier sind Beispiele, wie man statische oder dynamische Daten einrichtet:

• Statischer ID-Wert — Das URL-Format für diesen Datentyp ist: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Geben Sie die Sheet-ID in dieser URL an, damit der API-Aufruf immer genau dieses Sheet sortiert. 
• Dynamischer Run Log-Datenverweis — Das URL-Format für diese Daten ist: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. Statt die Sheet-ID hinzuzufügen, müssen Sie den Datenverweis des Sheets aus dem Run Log 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 spezifische Sheet, das in dieser URL angegeben ist.

Methode

Die Methode definiert die Art der Operationen, die Sie durchführen möchten. Definieren Sie eine Methode für jeden API-Aufruf im Modul API aufrufen. 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.

Header

„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.

Das Profil kann die für jeden Aufruf an ein System erforderlichen Header einrichten. In Ihrem Workflow ermöglicht das Modul „Make API Call“ die Konfiguration zusätzlicher Header für spezifische Aktionen. 

Formularparameter 

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

Ein Beispiel-Szenario wäre, Paging mit Smartsheet-Aufrufen anzuwenden, um einige Elemente in der Antwort einzuschließen. Zum Beispiel, wenn Sie nur die erste Seite eines Berichts mit 20.000 Zeilen abrufen möchten.

HTTP-Anforderungstext

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“ in diesem 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.

Ausgabe

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.

Voraussetzungen

• Ein Sheet 
  • Die Sheet-ID
  • Eine Spalte, die, wenn sie in Ihren Zeilen geändert wird, Ihren Bridge-Workflow auslöst
• Bridge
  • Smartsheet-Integration
  • Smartsheet Bridge-Workflow-Auslöser: Smartsheet – When Column Values are Changed
  • Bridge-Modul: Utilities > Call API > Make API Call
• Ein Smartsheet-API-Schlüssel.

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

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

Ziehen Sie alle Module, die Sie für den Workflow benötigen. 

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

Das sollten Sie in Ihrem Workflow sehen, wenn Sie fertig sind: 

Brandfolder Image

Einrichten des Workflow-Auslösers

1. Wählen Sie das Trigger-Modul aus.
2. Wählen Sie im Integrationen-Abschnitt die Integrationsseite aus.

3. Suchen Sie Smartsheet in der Integrationsliste.

   Sie können die Connected-Option unter dem 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 Trigger-Zeile.
5. Um einen neuen Auslöser zu erstellen, wählen Sie Zu Triggern hinzufügen 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).
   • Ereignistyp: Wählen Sie Wenn Spaltenwerte geändert werden aus. 
   • Spaltenname oder ID: Geben Sie den Namen der Smartsheet-Spalte ein, auf die Sie antworten möchten. Wenn Sie beispielsweise die Zeilen auf dem Sheet jedes Mal sortieren möchten, wenn sich die Priorität ändert, geben Sie den Namen Ihrer Prioritätsspalte ein.
   • Workflow auswählen: Wählen Sie den neuen Workflow, den Sie gerade erstellt haben, aus der Dropdown-Liste aus.
7. Wählen Sie Speichern aus.
8. Kopieren Sie die Spalten-ID in der Auslöserinfo. Sobald Sie den Workflow-Auslöser speichern, wird die Spalten-ID in der Triggerinfo verfügbar.
9. Fügen Sie es in Notepad 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.

Abrufen der API-Aufrufdetails

Dieser Workflow ändert den Wert in der Prioritätsspalte Ihres Sheets, das den Trigger auslöst. Sobald dieser Workflow den/die Auslöser erkennt, führt er die erforderlichen Aktionen für das jeweilige Sheet aus. Wir verwenden die Verweise auf die Laufzeitdaten (Run Log) des Auslösers, um die Smartsheet-Module auszufüllen.

Für diesen Workflow müssen Sie einen API-Aufruf an den Endpunkt Smartsheet Sort Sheet ausführen. 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, sind einige der erforderlichen Informationen für den API-Aufruf bereits eingerichtet. 

1. Navigieren Sie zum Tab Integrations.
2. Wählen Sie das Dienstprogramm Call API aus.
3. Erweitern Sie den Abschnitt Profiles im Tab Profiles.

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.  Die Basis-URL für Smartsheet ist https://api.smartsheet.com/2.0/.
7. Fügen Sie unter Secret Headers alle Header hinzu, die Token oder geheime Informationen wie API-Token enthalten.
   • In Smartsheet-Aufrufen haben Sie 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. Wählen Sie Speichern aus.
10. Kehren Sie zu Ihrem Workflow zurück.

Entwicklungstipp für Smartsheet Bridge

Die Basis-URL ist der Teil der URL der System-API, der immer gleich bleibt, unabhängig davon, was Sie in diesem System versuchen zu tun. Der Endpunkt im „Make API Call“-Modul ermöglicht es Ihnen, die spezifischen Details und Aktionen anzugeben, die Sie mit diesem API-Aufruf ausführen möchten.

Beispiel: Wir verwenden die Smartsheet-API, um ein Sheet zu sortieren. Die Basis-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. Daher müssen wir sheets/sheet_id_or_data_reference_here/sort in das Feld Endpoint des Moduls einfügen.

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

1. Wählen Sie im „Make API Call“-Modul Ihr gewünschtes API-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: Workflow testen

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, sind die sortierten Zeilen in auf- oder absteigender Reihenfolge (je nach Ihrer Konfiguration im Body des API-Aufrufs) der Werte, 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

• Trigger von einem anderen Sheet oder einer anderen Spalte als der, die Sie sortieren möchten. Dazu müssen Sie die Details des API Calls 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.: wenn die Priorität 0 ist, verschieben Sie die Zeile aus dem Sheet, und wenn die Priorität 1 ist, sortieren Sie das Sheet).
• Verwenden Sie einen Zeitplanauslöser. Wenn Sie diesen Auslöser verwenden, müssen Sie nicht auf Änderungen reagieren, da er das Sheet einmal täglich, wöchentlich oder monatlich sortiert.

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 einzigartiges Profil einrichten.
• Das Modul Make API Call ist erfolgreich, wenn es eine Antwort von der Ziel-API erhält, einschließlich wenn es einen Fehler erhält. Dies ist in späteren Schritten hilfreich, um Pfade in Ihrem Workflow für unerwartete Antworten von der API zu bestimmen (z. B. wenn der API-Aufruf einen Fehler zurückgibt, können Sie eine Aktualisierung an eine Zeile senden, die besagt, dass ein Problem aufgetreten ist). Wenn Sie möchten, dass der Workflow stoppt, wenn die API einen Fehler zurückgibt, können Sie das Kontrollkästchen im Abschnitt Zusätzliche Einstellungen des Moduls aktivieren.