API REST

Per i collegamenti al riferimento all'API di Oracle Cloud Infrastructure e una lista degli endpoint dell'API regionale, vedere Riferimento all'API e endpoint.

Il percorso di base dell'endpoint include la versione API desiderata (ad esempio, 20160918). Di seguito è riportato un esempio di richiesta POST per creare una nuova VCN nell'area Ashburn.

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

Oracle Cloud Infrastructure fornisce un preavviso di 12 mesi prima della data di rimozione o modifica di un'API esistente di un Cloud Service distribuito che richiederebbe l'aggiornamento del codice.

Tutte le richieste API di Oracle Cloud Infrastructure devono essere firmate per scopi di autenticazione. Per informazioni sulle credenziali richieste e su come firmare le richieste, vedere Richiedi firme.

Tutte le richieste API di Oracle Cloud Infrastructure devono supportare il protocollo HTTPS e SSL TLS 1.2.

Il codice di stato HTTP 401 (NotAuthenticated) viene restituito se l'orologio del client è distorto più di 5 minuti da quello del server. Per determinare l'ora di clock del server, utilizzare questo comando curl con l'endpoint API:

curl -s --head <endpoint> | grep Date

Ad esempio:

curl -s --head https://iaas.us-phoenix-1.oraclecloud.com | grep Date

Le API Oracle Cloud Infrastructure utilizzano richieste e risposte HTTP standard. Ciascuno può contenere intestazioni specifiche di Oracle per l'impaginazione, tag entità (ETags) e così via, come descritto altrove in questo argomento e nella documentazione API.

Ogni risposta include un ID richiesta univoco assegnato da Oracle (ad esempio, bb3f3275-f356-462a-93c4-bf40fb82bb02) nell'intestazione della risposta opc-request-id. Se è necessario contattare Oracle per informazioni su una richiesta specifica, fornire questo ID richiesta.

Molte operazioni API richiedono JSON nel corpo della richiesta o restituiscono JSON nel corpo della risposta. I contenuti specifici del file JSON sono descritti nella documentazione API per la singola operazione. Notare che la notazione JSON non è sottoposta a wrapping o etichettata in base al nome dell'operazione o al nome o al tipo dell'oggetto.

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"
}		

Se una richiesta genera un errore, la risposta contiene un codice di risposta HTTP standard con 4xx per gli errori del client e 5xx per gli errori del server. Il corpo include anche JSON con un codice di errore e una descrizione dell'errore. Ad esempio:

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

Per un elenco degli errori comuni in tutti i servizi, vedere Errori API.

Oracle Cloud Infrastructure applica la limitazione a molte richieste API per evitare l'uso accidentale o abusivo delle risorse. Se fai troppe richieste troppo velocemente, potresti vedere alcuni avere successo e altri fallire. Oracle consiglia di implementare un back-off esponenziale, a partire da pochi secondi fino a un massimo di 60 secondi. Quando una richiesta non riesce a causa della limitazione, il sistema restituisce il codice di risposta 429 e il seguente codice di errore e descrizione:

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

La maggior parte delle risorse Oracle Cloud Infrastructure, come le istanze di computazione, hanno cicli di vita. In molti casi, si desidera che il codice aspetti che una risorsa o una richiesta di lavoro raggiunga uno stato specifico oppure che venga superato un timeout prima di eseguire ulteriori azioni.

È possibile eseguire il polling di una risorsa per determinarne lo stato. Ad esempio, quando si chiama GetInstance, il corpo della risposta contiene una risorsa istanza che include l'attributo lifecycleState. Prima di continuare, potrebbe essere necessario che il codice aspetti l'esecuzione di lifecycleState dell'istanza.

Risorse diverse richiedono tempi diversi per la transizione tra gli stati. Pertanto, i parametri di frequenza e durata ottimali per una strategia di polling possono variare tra le risorse. I camerieri di Oracle Cloud Infrastructure SDK utilizzano la seguente strategia predefinita:

• Utilizzare un back-off esponenziale, a partire da pochi secondi a un massimo di 30 secondi tra i tentativi di polling.
• Eseguire il polling fino a 20 minuti, quindi interrompere.

In alternativa, ulteriori informazioni sui camerieri, vedere:

• SDK per la documentazione dei camerieri Java
• SDK per la documentazione dei camerieri Ruby

Se si utilizza l'API, per firmare le richieste sarà necessario l'OCID della tenancy (vedere Richiedi firme). Ne avrai bisogno anche per alcune operazioni dell'API IAM. Un OCID è un ID Oracle Cloud (vedere Identificativi delle risorse).

L'OCID tenancy è simile al seguente (notare la parola "tenancy" in esso contenuta): ocid1.tenancy.oc1..<unique_ID>.

La maggior parte delle operazioni elenco esegue la paginazione dei risultati. Ad esempio, i risultati vengono impaginati per l'operazione ListInstances nell'API Core Services. Quando si chiama un'operazione Elenco impaginato, la risposta indica più pagine di risultati includendo l'intestazione opc-next-page.

L'impaginazione delle liste per lo storage degli oggetti ListObjects funziona in modo diverso perché i controlli di impaginazione vengono utilizzati anche per il filtro dei nomi degli oggetti. ListObjects restituisce nextStartWith anziché opc-next-page nel corpo della risposta. Per eseguire la paginazione di più oggetti, utilizzare il valore nextStartWith restituito con il parametro start. Per filtrare gli oggetti restituiti da ListObjects, utilizzare i parametri start e end.

Per alcune operazioni è possibile fornire un token di nuovo tentativo univoco (opc-retry-token) in modo che la richiesta possa essere rieseguita in caso di timeout o errore del server senza il rischio di eseguire di nuovo la stessa azione. Il token scade dopo 24 ore, ma può essere invalidato prima a causa di operazioni in conflitto (ad esempio, se una risorsa è stata eliminata e rimossa dal sistema, è possibile che venga rifiutato un nuovo tentativo della richiesta di creazione originale).

L'API supporta gli etag ai fini di un controllo ottimale della concorrenza. Le chiamate GET e POST restituiscono un'intestazione di risposta etag con un valore da memorizzare. Quando in seguito si desidera aggiornare o eliminare la risorsa, impostare l'intestazione if-match sul valore ETag ricevuto per la risorsa. La risorsa verrà quindi aggiornata o eliminata solo se il valore ETag fornito corrisponde al valore corrente del valore ETag della risorsa.

Se si invia una stringa vuota ("") come valore di un parametro facoltativo, l'API convalida il valore come normale (ad esempio, verifica la lunghezza minima e massima consentita e così via). Spesso la lunghezza minima consentita è 1, quindi viene restituito un errore. Se non si imposta il valore (null), l'API non esegue alcuna convalida e potrebbe verificarsi un'altra azione. Ad esempio: se non si imposta un valore per displayName durante la creazione di un nuovo oggetto VCN, il servizio genererà automaticamente un valore.