API REST

Les API Oracle Cloud Infrastructure sont des API REST standard qui utilisent des demandes et des réponses HTTPS. Cette rubrique décrit les informations de base sur l'utilisation des API.

Adresses et référence d'API

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.

Version 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

Signature de la demande requise

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.

HTTPS et TLS 1.2 requis

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

Décalage maximal autorisé de l'horloge client

Le code de statut HTTP 401 (NotAuthenticated) est renvoyé si l'horloge du client est décalée de plus de 5 minutes par rapport à celle du serveur. Pour déterminer l'heure de l'horloge du serveur, utilisez la commande cURL avec l'adresse d'API :

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

Par exemple :

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

Format de demande et de réponse

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.

Remarque

Veillez à définir l'en-tête Content-Type sur application/json dans les demandes POST et PUT qui contiennent JSON dans le corps.

Exemple de demande CreateVcn


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

Exemple de réponse CreateVcn

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

Format d'erreur

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.

Ralentissement des demandes

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

Interrogation du statut des ressources

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 :

Emplacement de l'OCID de votre location

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).

Obtenez l'OCID de location à partir d'Oracle Cloud Infrastructure via la console sur la page Détails de location :

  1. Ouvrez le menu Profil (Icône du menu utilisateur), puis cliquez sur Location : <your_tenancy_name>.

  2. L'OCID de location est affiché sous Informations sur la location. Cliquez sur Copier pour le copier dans le presse-papiers.

    Page Détails de location indiquant l'emplacement de l'OCID de location

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

Pagination de liste

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 Liste paginée, la réponse indique d'autres pages de résultats en incluant l'en-tête opc-next-page.

Remarque

Une page peut être vide même s'il reste d'autres résultats. Chaque fois que l'en-tête opc-next-page apparaît, il y a plus d'éléments de liste à obtenir. Pour plus d'informations sur le contrôle des listes des ressources, reportez-vous à Présentation de Search.

La pagination de liste pour 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 paginer 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.

Procédure d'obtention de la page de résultats suivante

Effectuez une nouvelle demande GET vers la même URL, modifiée en définissant le paramètre de requête de page sur la valeur de l'en-tête opc-next-page. Répétez ce processus jusqu'à obtenir une réponse sans en-tête opc-next-page. L'absence de cet en-tête indique que vous avez atteint la dernière page de la liste.

Remarque

Pour ne pas écrire de code de pagination, reportez-vous aux fonctions du module de pagination fourni avec le kit SDK pour Python.
Procédure d'obtention de la page de résultats précédente
(Disponible avec certaines API.) Effectuez une nouvelle demande GET vers la même URL, modifiée en définissant le paramètre de requête de page sur la valeur de l'en-tête opc-prev-page. Répétez ce processus jusqu'à obtenir une réponse sans en-tête opc-prev-page. L'absence de cet en-tête indique que vous avez atteint la première page de la liste.
Remarque

Pour ne pas écrire de code de pagination, reportez-vous aux fonctions du module de pagination fourni avec le kit SDK pour Python.
Procédure de modification du nombre maximal de résultats par page

Dans la demande GET, définissez limit sur le nombre d'éléments à renvoyer dans la réponse.

Remarque

Le service ne renverra pas plus de résultats que le nombre indiqué par limit, mais peut ne pas renvoyer ce nombre exact.

Jeton de nouvelle tentative

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).

ETags pour le contrôle d'accès concurrentiel optimiste

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.

Chaînes NULL ou vides pour les paramètres facultatifs

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.