Die Samsara-Web-API ermöglicht den Zugriff auf alle Ihre Daten in der Samsara Cloud mithilfe einer HTTPS-basierten API im RPC-Stil. Verwenden Sie die API für den Zugriff auf:
Echtzeit- und historische Daten für jeden Zeitraum und jede Abtasthäufigkeit können angefordert werden
Daten zu Temperatur, Luftfeuchtigkeit, Leistung und Eingangsmodul verfügbar
Der Zugriff auf die API ist für alle Kunden aktiviert
Die Authentifizierungssicherheit wird durch ein API-Token- und Secret-Key-System bereitgestellt
Daten werden sicher im JSON-Format über TLS geliefert
API-Versionen werden regelmäßig veröffentlicht.
Ausführliche Informationen zur Samsara-API finden Sie im Entwicklerportal unter developer.samsara.com.
Sie können API-Token für den sicheren Zugriff auf die API auf der verwalten API-Token Einstellungsseite. Ausführliche Informationen zu API-Token finden Sie unter Authentifizierungsleitfaden.
Um ein API-Token zu erstellen, muss Ihnen die Rolle „Vollständiger Administrator“ oder „Standardadministrator“ oder a Benutzerdefinierte Rollen mit den folgenden Berechtigungen.
Berechtigungen bearbeiten, um API-Tokens anzuzeigen und zu bearbeiten
Bearbeitungsberechtigungen zum Erstellen, Bearbeiten und Löschen von Benutzern, Rollen und Tags
In beiden Fällen muss Ihre Rolle Zugriff haben, um die gesamte Organisation zu verwalten. Rollen, die Tags für reduzierten Umfang verwenden (auch bekannt als Administratoren auf Tag-Ebene), sind nicht ausreichend.
Sie können beliebig viele API-Token anfordern und löschen.
So richten Sie ein API-Token ein:
Wählen Sie das Symbol Einstellungen (
) am unteren Rand Ihres Samsara dashboard um Dashboard-Einstellungen anzuzeigen.-
Auswählen API-Token.
Klicken + Ein API-Token hinzufügen.
-
Definieren Sie die Token-Eigenschaften:
Geben Sie eine Beschreibung ein Name für Ihr API-Token, das den Hauptzweck beschreibt.
Wählen Sie die Stufe von Tag-Zugriff für Ihre Marke. Weitere Informationen zu Tags finden Sie unter Stichworte.
-
Wählen Sie eine Berechtigung aus Zielfernrohr für Ihr API-Token:
Speichern Ihre Änderungen.
-
Nachdem Sie das Token erstellt haben, kopieren Sie es wie unten gezeigt. Das Token wird unlesbar, nachdem die Seite aktualisiert wurde. Achten Sie also darauf, die Token-Zeichenfolge an einem sicheren Ort aufzuzeichnen.
Wenn Sie vergessen, ein API-Token zu kopieren oder verlieren, können Sie eine neue Token-Zeichenfolge generieren.
Anmerkung
Wenn eine Integration aktiv ein API-Token verwendet, wird sie unterbrochen, wenn Sie dieses API-Token neu generieren. Dies liegt daran, dass der vorherige Schlüssel gelöscht und durch einen neuen Schlüssel ersetzt wird. Seien Sie vor der Bestätigung entsprechend vorsichtig.
Wählen Sie das Symbol Einstellungen (
) am unteren Rand Ihres Samsara dashboard um Dashboard-Einstellungen anzuzeigen.Auswählen API-Token.
-
Im Menü Weitere Aktionen ( ... ) für das API-Token wählen Sie Regenerate (Regenerieren).
Klicken Copy to Clipboard (In die Zwischenablage kopieren) um den neuen Code zu kopieren und aufzuzeichnen.
Ersetzen Sie das API-Token überall dort, wo es verwendet wird.
Sie können die API-Token-Version in Ihrer Verwaltungskonsole aktualisieren. Samsara erhöht die API-Version nur, wenn es eine Breaking Change an der API gibt.
Beispiele für Breaking Changes sind:
Hinzufügen eines obligatorischen Anforderungsparameters zu vorhandenen API-Methoden
Entfernen von Eigenschaften aus vorhandenen API-Antworten
Bei Non-Breaking Changes sind diese in allen Versionen der API zugänglich.
Beispiele für unterbrechungsfreie Änderungen sind:
Hinzufügen neuer API-Ressourcen
Hinzufügen neuer optionaler Anforderungsparameter zu bestehenden API-Methoden
Hinzufügen neuer Eigenschaften zu bestehenden API-Antworten
Ändern der Reihenfolge von Eigenschaften in vorhandenen API-Antworten
Ändern der Länge oder des Formats von Objekt-IDs oder anderen undurchsichtigen Zeichenfolgen
Sie finden die Version auf der Seite API-Token im Dashboard:
Ein Upgrade Ihrer API-Version wirkt sich auf die API-Aufrufe aus, die Sie ohne einen Samsara-Version-Header durchführen: die Parameter, die Sie senden können, und die Struktur der zurückgegebenen Objekte.
Sie können eine neuere Version für einen API-Aufruf testen, indem Sie den Samsara-Version-Header festlegen. Im folgenden Beispielcode wird ein Benutzer mit der <01.01.2018 token> könnte a machen einmalig Anfrage für die 2019-02-22 Version durch Übergabe an X-Samsara-Version HTTP-Header mit der gewünschten Datestamp-Version:
GET -H "X-Samsara-Version: 2019-02-22" https://api.samsara.com/v1/fleet/list?access_token=<2018-01-01 token>
Wenn Sie sicher sind, dass Ihr Code mit der neuesten Version umgehen kann, klicken Sie auf Aktualisierung in Ihrem Samsara-Dashboard. Dadurch wird die Version gewechselt, die von API-Aufrufen ohne Samsara-Version-Header verwendet wird.
