API REST

Pour les liens vers les informations de référence sur l'API Oracle Cloud Infrastructure et la liste des points d'extrémité d'API régionaux, voir Informations de référence sur les API et points d'extrémité d'API.

Le chemin de base du point d'extrémité comprend la version d'API souhaitée (par exemple, 20160918). Voici un exemple pour une demande POST permettant de créer un nouveau réseau en nuage virtuel dans la région Ashburn :

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

Oracle Cloud Infrastructure vous annoncera avec un préavis de 12 mois toute suppression ou modification d'une API existante d'un service en nuage que vous avez déployé, nécessitant une mise à jour de votre code.

Pour plus d'informations, consultez la section 4.3 de la documentation de base sur les services Oracle PaaS Public Cloud et Oracle IaaS Public Cloud.

Toutes les demandes d'API Oracle Cloud Infrastructure doivent être signées aux fins d'authentification. Pour plus d'informations sur les données d'identification requises et la signature des demandes, voir Signatures des demandes.

Toutes les demandes d'API Oracle Cloud Infrastructure doivent prendre en charge le protocole HTTPS et SSL TLS 1.2.

Les API Oracle Cloud Infrastructure utilisent des demandes et des réponses HTTP standard. Chacune peut contenir des en-têtes propres à Oracle pour la pagination, les marqueurs d'entité (ETag), etc., comme décrit ailleurs dans cette rubrique et dans la documentation sur les API.

Chaque réponse comprend un ID demande unique affecté par Oracle (par exemple, bb3f3275-f356-462a-93c4-bf40fb82bb02) dans l'en-tête de réponse opc-request-id. Si vous devez communiquer avec Oracle à propos d'une demande particulière, indiquez cet ID demande.

Nombre d'opérations d'API nécessitent du code JSON dans le corps de la demande ou retournent du code JSON dans le corps de la réponse. Le contenu propre au code JSON est décrit dans la documentation sur l'API pour l'opération concernée. Notez que le format JSON n'est pas encapsulé ou étiqueté en fonction du nom de l'opération ou du nom ou du type de l'objet.

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

Si une demande génère une erreur, la réponse contient un code de réponse HTTP standard avec 4xx pour les erreurs de client et 5xx pour les erreurs de serveur. Le corps inclut également du code JSON avec un code d'erreur et une description de l'erreur. Par exemple :

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

Pour une liste des erreurs communes à tous les services, voir Erreurs d'API.

Oracle Cloud Infrastructure applique la limitation à de nombreuses demandes d'API pour prévenir l'utilisation accidentelle ou abusive des ressources. Si vous créez un trop grand nombre de demandes trop rapidement, il se peut que certaines d'entre elles réussissent et que d'autres échouent. Oracle recommande la mise en oeuvre d'un délai d'attente exponentiel, allant de quelques secondes à 60 secondes maximum. En cas d'échec d'une demande en raison de la limitation, le système retourne le code de réponse 429 ainsi que le code d'erreur et la description suivants :

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

La majorité des ressources Oracle Cloud Infrastructure, notamment les instances de calcul, comportent des cycles de vie. Dans la plupart des cas, vous voulez que votre code attende qu'une ressource ou une demande de travail ait atteint un état spécifique, ou qu'une temporisation soit dépassée, avant d'entreprendre une action supplémentaire.

Vous pouvez scruter une ressource pour déterminer son état. Par exemple, lorsque vous appelez GetInstance, le corps de la réponse contient une ressource d'instance qui inclut l'attribut lifecycleState. Vous voudrez peut-être que votre code attende que l'état du cycle de vie (lifecycleState) de l'instance soit RUNNING avant de continuer.

Le temps de transition d'un état à un autre diffère en fonction des ressources. Par conséquent, les paramètres de fréquence et de durée optimaux pour une stratégie de scrutation peuvent varier selon les ressources. Les processus en attente de trousse SDK Oracle Cloud Infrastructure utilisent la stratégie par défaut suivante :

• Utiliser un délai d'attente exponentiel, allant de quelques secondes à 30 secondes maximum, entre des tentatives de scrutation.
• Effectuer une scrutation de 20 minutes maximum, puis arrêter.

Pour plus d'informations sur les processus en attente, voir :

• Documentation sur les processus en attente de la trousse SDK pour Java
• Documentation sur les processus en attente de la trousse SDK pour Ruby

Si vous utilisez l'API, vous aurez besoin de l'OCID de votre location pour signer les demandes (voir Signatures des demandes). Vous en aurez également besoin pour certaines opérations de l'API GIA. Un OCID est un ID Oracle Cloud (voir Identificateurs de ressource).

L'OCID de la location se présente comme suit (notez le mot "tenancy" (location)) : ocid1.tenancy.oc1..<ID_unique>.

La plupart des opérations de liste paginent les résultats. Par exemple, les résultats sont paginés pour l'opération ListInstances dans l'API Services de base. Lorsque vous appelez une opération de liste paginée, la réponse indique des pages supplémentaires de résultats en incluant l'en-tête opc-next-page.

La pagination de liste pour la commande ListObjects du service de stockage d'objets fonctionne différemment, car les contrôles de pagination sont également utilisés pour le filtrage de nom d'objet. ListObjects retourne nextStartWith au lieu d'opc-next-page dans le corps de la réponse. Pour effectuer la pagination pour un plus grand nombre d'objets, utilisez la valeur nextStartWith retournée avec le paramètre start. Pour filtrer les objets que ListObjects doit retourner, utilisez les paramètres start et end.

Pour certaines opérations, vous pouvez fournir un jeton de nouvelle tentative unique (opc-retry-token), de sorte que la demande puisse être retentée en cas de temporisation ou d'erreur de serveur sans risque de réexécution de la même action. Le jeton expire après 24 heures, mais peut être invalidé avant en raison d'opérations conflictuelles (par exemple, si une ressource a été supprimée et épurée du système, une nouvelle tentative de la demande de création initiale peut être rejetée).

L'API prend en charge les marqueurs d'entité (etag) à des fins de contrôle de simultanéité optimiste. Les appels GET et POST retournent un en-tête de réponse etag contenant une valeur à stocker. Si vous souhaitez, par la suite, mettre à jour ou supprimer la ressource, réglez l'en-tête if-match à la valeur ETag que vous avez reçue pour la ressource. La ressource sera alors mise à jour ou supprimée seulement si la valeur ETag que vous fournissez correspond à la valeur courante de l'élément 'ETag de cette ressource.

Si vous envoyez une chaîne vide ("") en tant que valeur d'un paramètre facultatif, l'API valide la valeur comme normale (par exemple, les vérifications par rapport à la longueur minimale ou maximale autorisée, etc.). Comme la longueur minimale autorisée est souvent 1, une erreur serait retournée. Si vous ne définissez pas la valeur (elle est nulle), l'API n'effectue aucune validation et d'autres actions peuvent survenir. Par exemple, si vous ne définissez pas de valeur pour displayName lors de la création d'un objet de réseau en nuage virtuel, le service génèrera automatiquement une valeur.