REST-APIs

Links zur Oracle Cloud Infrastructure-API-Referenz und eine Liste der regionalen API-Endpunkte finden Sie unter API-Referenz und -Endpunkte.

Der Basispfad des Endpunkts enthält die gewünschte API-Version (Beispiel: 20160918). Im Folgenden finden Sie ein Beispiel für eine POST-Anforderung zum Erstellen eines neuen VCN in der Region "Ashburn":

POST https://iaas.us-ashburn-1.oraclecloud.com/20160918/vcns

Oracle Cloud Infrastructure kündigt die Entfernung oder Änderung einer vorhandenen API eines Cloud-Service, den Sie bereitgestellt haben, 12 Monate im Voraus an, wenn dies eine Aktualisierung Ihres Codes erfordert.

Weitere Informationen finden Sie in Abschnitt 6.3 in der Pillar-Dokumentation zu Oracle PaaS und IaaS Public Cloud Services.

Alle Oracle Cloud Infrastructure-API-Anforderungen müssen zu Authentifizierungszwecken signiert werden. Informationen zu den erforderlichen Zugangsdaten und zum Signieren der Anforderungen finden Sie unter Anforderungssignaturen.

Alle Oracle Cloud Infrastructure-API-Anforderungen müssen HTTPS und SSL-Protokoll TLS 1.2 unterstützen.

Die Oracle Cloud Infrastructure-APIs verwenden standardmäßige HTTP-Anforderungen und -Antworten. Jede kann Oracle-spezifische Header für Paginierung, Entitytags (ETags) usw. enthalten, wie an anderer Stelle in diesem Thema und in der API-Dokumentation beschrieben.

Jede Antwort umfasst eine eindeutige, von Oracle zugewiesene Anforderungs-ID (z.B. bb3f3275-f356-462a-93c4-bf40fb82bb02) im Antwortheader opc-request-id. Wenn Sie Oracle bezüglich einer bestimmten Anforderung kontaktieren müssen, geben Sie diese Anforderungs-ID an.

Viele der API-Vorgänge erfordern JSON im Anforderungstext oder geben JSON im Antworttext zurück. Der genaue Inhalt der JSON wird in der API-Dokumentation für den jeweiligen Vorgang beschrieben. Beachten Sie, dass die JSON nicht entsprechend dem Vorgangsnamen oder Objektnamen oder -typ gekürzt oder beschriftet ist.

POST https://iaas.us-phoenix-1.oraclecloud.com/20160918/vcns
host: iaas.us-phoenix-1.oraclecloud.com
opc-retry-token: 239787fs987
Content-Type: application/json
HTTP headers required for authentication
Other HTTP request headers per the HTTP spec

{
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
  "displayName": "Apex Virtual Cloud Network",
  "cidrBlock": "172.16.0.0/16"
}

200 OK
opc-request-id: 6c4d01a6-f764-4325-a3f8-720c8b5cae7b

{
   "id": "ocid1.vcn.oc1.phx.aaaaaaaa4ex5pqjtkjhdb4h4gcnko7vx5uto5puj5noa5awznsqpwjt3pqyq",
   "compartmentId": "ocid1.compartment.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq",
   "displayName": "Apex Virtual Cloud Network",
   "cidrBlock": "172.16.0.0/16"
   "defaultRouteTableId": "ocid1.routetable.oc1.phx.aaaaaaaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdsq",
   "defaultSecurityListId": "ocid1.securitylist.oc1.phx.aaaaaaaac6h4ckr3ncbxmvwinfvzxjbr7owu5hfzbvtu33kfe7hgscs5fjaq"
   "defaultDhcpOptionsId": "ocid1.dhcpoptions.oc1.phx.aaaaaaaawglzn7s5sogyfznl25a4vxgu76c2hrgvzcd3psn6vcx33lzmu2xa"
   "state": "PROVISIONING",
   "timeCreated": "2016-07-22T17:43:01.389+0000"
}		

Wenn eine Anforderung zu einem Fehler führt, enthält die Antwort einen HTTP-Standardantwortcode mit 4xx für Clientfehler und 5xx für Serverfehler. Der Text enthält außerdem JSON mit einem Fehlercode und einer Beschreibung des Fehlers. Beispiel:

{
    "code": "InvalidParameter",
    "message": "Description may not be empty; description size must be between 1 and 400"
}

Eine Liste der häufigen Fehler für alle Services finden Sie unter API-Fehler.

Oracle Cloud Infrastructure setzt Throttling bei vielen API-Anforderungen ein, um eine unbeabsichtigte oder falsche Verwendung von Ressourcen zu verhindern. Wenn Sie zu viele Anforderungen zu schnell ausführen, verlaufen einige möglicherweise erfolgreich, andere nicht. Oracle empfiehlt, ein exponentielles Backoff zwischen wenigen Sekunden und höchstens 60 Sekunden zu implementieren. Wenn eine Anforderung aufgrund von Throttling nicht erfolgreich ist, gibt das System den Antwortcode 429 und den folgenden Fehlercode mit dieser Beschreibung zurück:

{
      "code": "TooManyRequests",
      "message": "User-rate limit exceeded."
}

Die meisten Oracle Cloud Infrastructure-Ressourcen, wie Compute-Instanzen, haben Lebenszyklen. In vielen Fällen soll der Code warten, bis eine Ressource oder Arbeitsanforderung  einen bestimmten Status erreicht oder ein Timeout überschritten wird, bevor weitere Aktionen ausgeführt werden.

Sie können eine Ressource abfragen, um ihren Status zu bestimmen. Beispiel: Wenn Sie GetInstance aufrufen, enthält der Antworttext eine Instanzressource, die das Attribut lifecycleState enthält. Möglicherweise soll der Code warten, bis der Wert für lifecycleState der Instanz RUNNING lautet, bevor fortgefahren wird.

Verschiedene Ressourcen brauchen unterschiedlich lang für den Übergang zwischen Status. Deshalb können die optimalen Parameter für Häufigkeit und Dauer in einer Polling-Strategie zwischen den Ressourcen variieren. Die Oracle Cloud Infrastructure-SDK-Wartevorgänge verwenden die folgende Standardstrategie:

• Verwenden Sie ein exponentielles Backoff zwischen wenigen Sekunden bis maximal 30 Sekunden zwischen Polling-Versuchen.
• Führen Sie das Polling für bis zu 20 Minuten durch, und stoppen Sie es dann.

Alternativ finden Sie weitere Informationen zu Wartevorgängen unter:

• SDK für Java - Dokumentation zu Wartevorgängen
• SDK für Ruby - Dokumentation zu Wartevorgängen

Wenn Sie die API verwenden, benötigen Sie die OCID Ihres Mandanten , um die Anforderungen zu signieren (siehe Anforderungssignaturen). Sie ist auch für einige der IAM-API-Vorgänge erforderlich. Eine OCID ist eine Oracle Cloud-ID (siehe Ressourcen-IDs).

Die Mandanten-OCID sieht etwa folgendermaßen aus (beachten Sie das Wort "tenancy" darin): ocid1.tenancy.oc1..<unique_ID>.

Die meisten Listenvorgänge paginieren die Ergebnisse. Beispiel: Ergebnisse werden für den Vorgang ListInstances in der Coreservices-API paginiert. Wenn Sie einen paginierten Listenvorgang aufrufen, gibt die Antwort zusätzliche Seiten mit Ergebnissen an, wenn der opc-next-page-Header einbezogen wird.

Die Listenpaginierung für Object Storage ListObjects funktioniert anders, da die Paginierungssteuerelemente auch für die Objektnamensfilterung verwendet werden. ListObjects gibt nextStartWith anstatt opc-next-page im Antwortbody zurück. Um durch mehr Objekte zu paginieren, verwenden Sie den zurückgegebenen nextStartWith-Wert mit dem start-Parameter. Um zu filtern, welche Objekte ListObjects zurückgibt, verwenden Sie die Parameter start und end.

Bei einigen Vorgängen können Sie ein eindeutiges Wiederholungstoken angeben (opc-retry-token), sodass die Anforderung bei einem Timeout oder Serverfehler wiederholt werden kann, ohne dass dieselbe Aktion erneut ausgeführt werden muss. Das Token läuft nach 24 Stunden ab, kann jedoch bei in Konflikt stehenden Vorgängen vorher deaktiviert werden. (Beispiel: Wenn eine Ressource gelöscht und aus dem System entfernt wurde, kann eine Wiederholung der ursprünglichen Erstellungsanforderung abgelehnt werden.)

Die API unterstützt Entitytags für die optimistische Nebenläufigkeitssteuerung. Die GET- und POST-Aufrufe geben einen etag-Antwortheader mit einem Wert zurück, den Sie speichern sollten. Wenn Sie die Ressource später aktualisieren oder löschen möchten, setzen Sie den if-match-Header auf das Entitytag, das Sie für die Ressource erhalten haben. Die Ressource wird dann nur aktualisiert oder gelöscht, wenn das von Ihnen angegebene Entitytag mit dem aktuellen Wert der Ressource dieses Entitytags übereinstimmt.

Wenn Sie eine leere Zeichenfolge ("") als Wert eines optionalen Parameters senden, validiert die API den Wert als normal. (Beispiel: Minimal und maximal zulässige Länge usw. werden geprüft.) Die minimal zulässige Länge beträgt häufig 1, daher wird ein Fehler zurückgegeben. Wenn Sie den Wert nicht festlegen (er also Null lautet), führt die API keine Validierung durch, und es kann eine andere Aktion auftreten. Beispiel: Wenn Sie beim Erstellen eines neuen VCN-Objekts keinen Wert für displayName festlegen, generiert der Service automatisch einen Wert.