APIs - Grundlegende Informationen

Die Samsara Web API ermöglicht Ihnen den Zugang zu all Ihren Daten in der Samsara Cloud über eine HTTPS-basierte API im RPC-Stil. Genauere Informationen finden Sie im API-Leitfaden: developers.samsara.com

Zentrale Punkte:

• Möglichkeit der Anforderung von Echtzeit- und historischen Daten für jeden Zeitraum und jede Abtastfrequenz
• Verfügbarkeit von Daten zur Temperatur, Luftfeuchtigkeit, Strom und Input-Modul
• Zugang zur API für alle Kunden aktiviert
• Authentifizierungssicherheit durch API-Token und geheimen Schlüssel
• Daten werden in JSON-Format über TLS sicher geliefert

API-Tokens erstellen

API Tokens für einen sicheren Zugriff auf die API werden auf der Seite API Tokens Settings (API Tokens Einstellungen) angezeigt und können dort erstellt werden. Unten finden Sie die Anweisungen zur Einrichtung eines API-Tokens:

1. Gehen Sie in Ihrem Samsara Dashboard auf Settings (Einstellungen) > API Tokens.
2. Klicken Sie auf + Add an API Token (+ API Token hinzufügen), um ein neues Token zu erstellen.

• Suchen Sie einen Namen für Ihr API Token aus. Wir empfehlen die Erstellung eines neuen API Tokens mit aussagefähigem Namen für jede Anwendung, die Sie erstellen.
• Wählen Sie die Art der Berechtigung (Scope) für Ihr API Token aus - entweder Read-only Admin (Administrator mit Lesezugriff) or Full Admin (Administrator mit vollem Zugriff).

3. Klicken Sie auf Save (Speichern), sobald Sie einen Namen und die Berechtigungsart eingegeben haben. 

Sie können so viele API Tokens anfordern und löschen, wie Sie wünschen. 

Es erscheinen regelmäßig neue API-Versionen. Informationen zu Versionen finden Sie auf https://developers.samsara.com/.

Bitte beachten Sie, dass Administratoren, die nur Lesezugriff haben, API Tokens nicht im Samsara Dashboard ansehen und erstellen können. 

Upgrade von API-Tokens

Sie können ein Upgrade einer API-Token-Version in Ihrer Admin-Konsole vornehmen. Samsara erhöht die API-Versionsnummer nur, wenn es grundlegende Änderungen bei der API gibt.

Beispiele für grundlegende Änderungen: 

• Hinzufügen eines obligatorischen Abfrageparameters zu bestehenden API-Methoden
• Löschen von Eigenschaften bei bestehenden API-Antworten

Nicht grundlegende Änderungen sind für alle Versionen der API nutzbar.

Beispiele für nicht grundlegende Änderungen:

• Hinzufügen neuer API-Ressourcen
• Hinzufügen eines optionalen Abfrageparameters zu bestehenden API-Methoden
• Hinzufügen neuer Eigenschaften zu bestehenden API-Antworten
• Änderung der Reihenfolge der Eigenschaften bei bestehenden API-Antworten
• Änderung der Länge oder des Formats von Objekt-IDs oder anderer undurchsichtiger Zeichenketten

Wie Sie Ihre API-Version upgraden

Sie finden die Version auf der Seite „API Tokens“ im Dashboard: 

Ein Upgrade Ihrer API-Version hat Auswirkungen auf die API-Aufrufe, die Sie ohne einen Samsara-Version-Header machen: die Parameter, die Sie senden 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 einstellen. Im Beispiel-Code unten konnte ein Benutzer mit dem <2018-01-01 token> eine einmalige Anforderung für die 2019-02-22-Version durch die Übermittlung eines X-Samsara-Version HTTP Headers mit der gewünschten Version mit Datumsstempel machen:

GET -H "X-Samsara-Version: 2019-02-22" https://api.samsara.com/v1/fleet/list?access_token=<2018-01-01 token>

Sobald Sie sicher sind, dass Ihr Code mit der neuesten Version kompatibel ist, klicken Sie auf „Upgrade“ in Ihrem Dashboard. Dadurch ändert sich die Version, die bei API-Aufrufen mit Nicht-Samsara-Version-Headern genutzt wird.