ᅢワbersicht ᅢᄐber SoftLayer-APIs

Die Anwendungsprogrammierschnittstelle von SoftLayer (API) ist die Entwicklungsschnittstelle, die Entwicklern und Systemadministratoren die direkte Interaktion mit dem Back-End-System von SoftLayer ermöglicht. Mit der Funktionalität unserer API können Benutzer über Fernzugriff Server verwalten und überwachen sowie Informationen von den verschiedenen SoftLayer-Systemen beispielsweise für Abrechnung, Bestand und DNS abrufen. Die API unterstützt viele der Features im SoftLayer-Kundenportal. Das heißt, wenn eine Interaktion im Kundenportal möglich ist, kann sie auch in der API durchgeführt werden.

Wer sollte die API verwenden?

Die SoftLayer-API (SLAPI) steht allen SoftLayer-Kunden ohne Aufpreis zur Verfügung. Wir unterstützen unsere Kunden mit Grundkenntnissen in der objektorientierten Programmierung dabei, die Funktionalität der SLAPI optimal zu nutzen. SoftLayer-Kunden verwenden die SLAPI für die verschiedensten Aufgaben. Gleichzeitig führt die Möglichkeit, über das Programm mit allen Teilen der SoftLayer-Umgebung in der API zu interagieren, dazu, dass der Großteil unserer Kunden die SLAPI zur Automatisierung von Aufgaben verwendet.

Verwendung der SoftLayer-API

Einführung

Über die SLAPI können Benutzer direkt mit den Objekten interagieren, die das Kundenportal ausführen. Bevor mit Entwicklungsarbeiten für die SLAPI begonnen wird, sollten Grundkenntnisse in Bezug auf Konzepte objektorientierter Programmierung wie Objekte, Eigenschaften, Verfahren und Übernahme vorhanden sein. Die SLAPI-Verfahren werden für Serviceobjekte in unseren Back-End-Systemen ausgeführt, die sowohl SoftLayer-spezifische Datentypobjekte als auch Standarddatentypen wie ganze Zahlen, boolesche Zahlen und Zeichenfolgen zurückgeben.
Die SLAPI ist ein Remote Procedure Call-System. Bei jedem Aufruf werden Daten an einen API-Endpunkt gesendet und im Gegenzug werden strukturierte Daten empfangen. Das Format, das für das Senden und Empfangen von Daten über die SLAPI verwendet wird, hängt von der ausgewählten API-Implementierung ab. Die SLAPI verwendet derzeit SOAP, XML-RPC oder REST für die Datenübertragung. Bevor Sie einen API-Aufruf starten, sollten Sie wissen, wie diese Protokolle in Ihrer Programmier- oder Scripting-Sprache verwendet werden. Sie können beliebige Teile der Implementierung in Ihrer Anwendung verwenden. In unserem GitHub-Profil stellen wir zudem einige servicespezifische API-Clients in verschiedenen unterstützen Sprachen zur Verfügung.

Einen API-Benutzer erstellen

Jeder Aufruf der SLAPI wird durch einen Kundenportalaccount authentifiziert. Accounts im Kundenportal können mehrere Benutzer enthalten und wir empfehlen ausdrücklich die Erstellung eines eindeutigen Kundenportalbenutzers zur Durchführung von API-Aufrufen. Ganz gleich, ob Sie eine Anwendung entwickeln oder eine von Dritten entwickelte API-basierte Anwendung verwenden, müssen Sie sich in Ihrem Programm authentifizieren, um auf Informationen zu Ihrem Account zugreifen und mit allen Funktionen interagieren zu können. Für die Authentifizierung an der SLAPI sind Kundenportal-Benutzername und API-Schlüssel, ein spezieller Authentifizierungstoken, der für API-Methodenaufrufe reserviert ist, erforderlich. Die im Kundenportal definierten Benutzerberechtigungen werden in den API-Aufrufen abgebildet.

Das öffentliche oder das private Netzwerk auswählen

SLAPI-Endpunktserver gibt es sowohl in den öffentlichen als auch in den privaten Netzwerken von SoftLayer. Ihre API-basierten Anwendungen können eine Verbindung von einem beliebigen Host im Internet herstellen; das private Netzwerk von SoftLayer bietet jedoch zusätzliche Datensicherheit. Darüber hinaus bietet SoftLayer eine Vielzahl von API-Endpunkten im privaten Netzwerk, auf die nur zugegriffen werden kann, wenn eine Verbindung zum privaten Netzwerk besteht. Alle Server und Instanzen für die Datenverarbeitung, die einem SoftLayer-Account zugeordnet sind, haben eine Direktverbindung zum privaten Netzwerk und erfordern keine zusätzliche Authentifizierung. Wenn Sie private Endpunkte von einem anderen Gerät aus nutzen möchten, ist eine VPN-Verbindung in unser privates Netzwerk erforderlich.

Grundlegende API-Konzepte

Services

Ein Service ist ein Endpunkt, der internen SoftLayer-Systemen zugeordnet ist. Jeder Service ist eine Gruppe von Methoden oder Aktionen, die ausgeführt werden können. Eine Liste aller SLAPI-Services ist im Abschnitt Referenz dieser Website zu finden.
Bei Zugriff auf den Abschnitt „Services“ für die gewünschte API wird auf der linken Seite des Bildschirms eine Liste aller verfügbaren Services angezeigt. Alle SoftLayer-Services beginnen mit „SoftLayer_“ und enthalten zusätzliche Bedingungen, die die allgemeine Funktion des Service definieren: „Hardware“, „Account“, „Billing“, „Network“ etc. Jeder Service wird dann um einen Namen erweitert, der die spezielle Funktion des Service in dieser speziellen Untergruppe definiert. Jeder Service, der der SoftLayer-API zugeordnet ist, hat einen eindeutigen Namen. Während einige Services, wie z. B. SoftLayer_Account und SoftLayer_Account_Address, einen gemeinsamen Präfix haben, ist deren Interaktion nicht unbedingt ähnlich und es gibt keine direkte Übernahme für Services mit einem ähnlichen Namen. Aus diesem Grund sollten alle Services einzeln betrachtet werden.
Klicken Sie auf den Servicenamen, um Einzelheiten zu einem bestimmten Service anzuzeigen. Auf der Seite eines Service ist eine Liste von Methoden enthalten, die für diesen Service verfügbar sind; viele enthalten auch eine kurze Übersicht zur Erläuterung des Service. Jeder Service umfasst spezielle Methoden und einige Services bieten die getObject-Methode. Diese Methoden können verwendet werden, um ein Objekt desselben Typs von der API abzurufen. Wenn Sie z. B. die getObject-Methode im SoftLayer_Network_Subnet-Service aufrufen, wird ein SoftLayer_Network_Subnet-Datentypobjekt zurückgegeben.

Methoden

Eine Methode ist eine bestimmte Aktion, die für einen SLAPI-Service ausgeführt werden kann. Jede Methode gibt einen Skalar oder einen strukturierten Datentyp zurück und kann bestimmte Parameter, Berechtigungen oder Header zur Ausführung erfordern. Methodenparameter sollten unter Verwendung der Verfahren weitergegeben werden, die in der Dokumentation für die einzelnen Sprachen oder Endpunkte beschrieben sind. In Situationen, in denen mehrere Parameter benötigt werden, geben Sie die Parameter in der Reihenfolge weiter, in der sie auf der Seite mit den Methoden von oben nach unten angezeigt werden. Im nachstehenden Screenshot sind die erforderlichen Parameter für die Methode SoftLayer_Monitoring_Agent::getGraph dargestellt. Wenn Sie diese Methode ausführen, geben Sie die Parameter in der folgenden Reihenfolge weiter: configurationValues, beginDate, endDate.
NOT FOUND: parameters.png
Eine vollständige Liste mit Parametern, Berechtigungen und Headern ist auf jeder Seite mit Methoden enthalten.

Datentypen

Ein Datentyp ist eine Struktur, die eine Gruppe skalarer Werte und andere Datentypen enthält. Zusätzlich zu den traditionellen skalaren Werten wie Zeichenfolgen, booleschen Werten oder ganzen Zahlen verwendet die SLAPI auch komplexe Datentypen mit Eigenschaften, die die Objekte definieren, die an Methoden in der SLAPI weitergegeben und von diesen zurückgegeben werden. Jeder Datentyp enthält ggf. eine Anzahl von lokalen, relationalen und Zähl-Eigenschaften.

Lokale Eigenschaften

Eine lokale Eigenschaft ist ein direkt untergeordnetes Element eines Datentyps. Lokale Eigenschaften werden normalerweise zurückgegeben, wenn getObject() aufgerufen wird. Es sind einige, wenn nicht sogar alle lokalen Eigenschaften erforderlich, wenn eine Instanz dieses Datentyps beim Aufruf von createObject() erstellt wird.

Relationale Eigenschaften

Eine relationale Eigenschaft ist ein indirekt untergeordnetes Element eines Datentyps. Relationale Eigenschaften werden in anderen Datentypen oder deren Eigenschaften definiert. Beispielsweise verfügt der Datentyp SoftLayer_Account über eine relationale Eigenschaft für Hardware. Diese relationale Eigenschaft ist ein Array von SoftLayer_Hardware-Datentypen. Wenn diese Eigenschaft mit einer Objektmaske ausgewählt wird, gibt sie ein Array zurück, das für jede Hardwareeinheit im Account ein SoftLayer_Hardware-Objekt enthält.

Zähleigenschaften

Eine Zähleigenschaft ist eine optionale Eigenschaft, die verwendet werden kann, um die Gesamtzahl Objekte zu bestimmen, die einer Eigenschaft zugeordnet sind. Beispielsweise kann die Gesamtzahl VLANs, die zu einem bestimmten Server gehören, unter Verwendung einer Objektmaske mit Softlayer_Hardware_Server->networkVlanCount abgerufen werden.

Erweiterte API-Konzepte

Zusätzlich zu den typischen Aktionen zum Erstellen, Lesen, Aktualisieren und Löschen können Entwickler mit der SLAPI definieren, wie Daten von den einzelnen Aufrufen zurückgegeben werden. Dies erfolgt unter Verwendung bestimmter API-Aufrufheader. Diese Header ermöglichen eine zusätzliche Kontrolle über das Datenvolumen, das von der API zurückgegeben wird.

Ergebnisbegrenzungen

Eine Ergebnisbegrenzung ist eine Unterstützungsmethode, mit der Sie einen Offset und eine Anzahl Objekte, die zurückgegeben werden sollen, definieren können. Damit können Seitenumbrüche für große Datasets durchgeführt werden.

Objektmasken

Mit einer Objektmaske kann der Benutzer angeben, welche lokalen Eigenschaften von einer Methode zurückgegeben werden sollen, und Informationen aus relationalen Eigenschaften und Zähleigenschaften abrufen. Eine Übersicht oder „mask“ wird erstellt, um die Daten zu definieren, die in den Rückgabewert aufgenommen werden sollen. Beispielsweise können die IDs für die einzelnen VLANs eines SoftLayer_Hardware_Server zusammengestellt werden, indem eine Objektmaske für „networkVlans.id“ beim Aufruf von SoftLayer_Hardware_Server::getObject angegeben wird.

Die SLAPI können Sie am besten steuern, indem Sie durch Objektmasken navigieren, um die gewünschten Ergebnisse zu erzielen. Häufig gibt es mehr als eine Möglichkeit, zu einem bestimmten Datenpunkt zu kommen, wobei einige effizienter als andere sein können.

Weitere Schritte

Jetzt, wo Sie die Grundlagen kennen, ist es Zeit, mit dem Codieren zu beginnen. Sehen Sie sich den Getting Started Guide an, um zu erfahren, wie Sie einen API-Benutzer erstellen und ihren ersten Aufruf durchführen können. Es stehen zudem eine Reihe Handbücher für bestimmte Sprachen zur Verfügung:

Andere nützliche Links: