API REST

Pour obtenir les liens vers la référence d'API Oracle Cloud Infrastructure et la liste des adresses d'API régionales, reportez-vous à Adresses et référence d'API.

Le chemin de base de l'adresse inclut la version d'API souhaitée (par exemple, 20160918). Voici un exemple de demande POST pour créer un réseau cloud virtuel dans la région Ashburn :

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

Oracle Cloud Infrastructure fournit un préavis de 12 mois avant la date de suppression ou de modification d'une API existante d'un service cloud que vous avez déployé qui vous oblige à mettre à jour votre code.

Pour plus d'informations, reportez-vous à la section 6.3 de la documentation pilier des services Oracle PaaS et IaaS Public Cloud.

Toutes les demandes d'API Oracle Cloud Infrastructure doivent être signées à des fins d'authentification. Pour plus d'informations sur les informations d'identification requises et sur la façon de signer les demandes, reportez-vous à Signatures des demandes.

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

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

Chaque réponse inclut un ID de 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 contacter Oracle à propos d'une demande particulière, indiquez cet ID de demande.

De nombreuses opérations d'API exigent JSON dans le corps de la demande ou renvoient JSON dans le corps de la réponse. Le contenu spécifique du JSON est décrit dans la documentation d'API pour chaque opération. Le JSON n'est pas encapsulé ou libellé 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 client et 5xx pour les erreurs de serveur. Le corps inclut également 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 obtenir la liste des erreurs communes à tous les services, reportez-vous à Erreurs d'API.

Oracle Cloud Infrastructure applique un ralentissement à de nombreuses demandes d'API pour éviter l'utilisation accidentelle ou abusive des ressources. Si vous effectuez un trop grand nombre de demandes trop rapidement, certaines peuvent aboutir et d'autres échouer. Oracle vous recommande d'implémenter un délai d'attente exponentielle, allant de quelques secondes à 60 secondes au maximum. Lorsqu'une demande échoue en raison d'un ralentissement, le système renvoie le code de réponse 429, ainsi que le code d'erreur et la description ci-après :

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

La plupart des ressources Oracle Cloud Infrastructure, telles que les instances de calcul, ont des cycles de vie. Dans la plupart des cas, le code doit attendre qu'une ressource ou qu'une demande de travail  atteigne un état spécifique, ou qu'un délai d'expiration soit dépassé, avant d'effectuer une autre action.

Vous pouvez interroger 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 pouvez souhaiter que le code attende que l'attribut lifecycleState de l'instance soit RUNNING avant de poursuivre.

La durée de transition pour passer d'un état à l'autre varie selon les ressources. Par conséquent, la fréquence et les paramètres de durée optimaux pour une stratégie d'interrogation peuvent varier d'une ressource à l'autre. Les processus en attente du kit SDK Oracle Cloud Infrastructure utilisent la stratégie par défaut suivante :

• Utilisation d'un délai d'attente exponentielle, allant de quelques secondes à 30 secondes au maximum entre les tentatives d'interrogation.
• Interrogation pendant 20 minutes au maximum, puis arrêt.

Pour plus d'informations sur les processus en attente, consultez les références ci-dessous :

• Documentation sur les processus en attente du kit SDK pour Java
• Documentation sur les processus en attente du kit SDK pour Ruby

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

L'OCID de location se présente comme suit (le mot "tenancy" y figure) : ocid1.tenancy.oc1..<unique_ID>.

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

La pagination de liste pour l'opération Object Storage ListObjects fonctionne différemment car les contrôles de pagination sont également utilisés pour le filtrage des noms d'objet. ListObjects renvoie nextStartWith au lieu de opc-next-page dans le corps de réponse. Pour parcourir plus d'objets, utilisez la valeur nextStartWith renvoyée avec le paramètre start. Pour filtrer les objets renvoyés par ListObjects, 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 d'expiration ou d'erreur de serveur sans risquer de réexécuter cette même action. Le jeton expire au bout de 24 heures, mais peut être invalidé avant la fin de ce délai en raison d'opérations en conflit (par exemple, si une ressource a été supprimée et purgée du système, une nouvelle tentative de la demande de création d'origine peut être rejetée).

L'API prend en charge les ETags dans le cadre du contrôle d'accès concurrentiel optimiste. Les appels GET et POST renvoient un en-tête de réponse etag avec une valeur que vous devez stocker. Lorsque vous voulez mettre à jour ou supprimer la ressource ultérieurement, définissez l'en-tête if-match sur l'ETag que vous avez reçue pour la ressource. La ressource sera alors mise à jour ou supprimée uniquement si l'ETag que vous indiquez correspond à la valeur en cours de l'ETag de cette ressource.

Si vous envoyez une chaîne vide ("") comme valeur d'un paramètre facultatif, l'API valide la valeur comme étant normale (par exemple, elle vérifie les longueurs minimale et maximale autorisées, etc.). Souvent, la longueur minimale autorisée est de 1 ; une erreur serait alors renvoyée. Si vous ne définissez pas la valeur (la valeur est NULL), l'API n'effectue aucune validation et une autre action peut se produire. Par exemple, si vous ne définissez pas de valeur pour displayName lors de la création d'un objet de réseau cloud virtuel, le service génère automatiquement une valeur.