API de REST

Para ver los enlaces a la referencia de API de Oracle Cloud Infrastructure y una lista de los puntos finales de API regionales, consulte Puntos finales y referencia de API.

La ruta de acceso base del punto final incluye la versión de API deseada (por ejemplo, 20160918). Este es un ejemplo de una solicitud POST para crear una nueva VCN en la región de Ashburn:

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

Oracle Cloud Infrastructure proporcionará una notificación anticipada 12 meses antes de la fecha de eliminación o cambio de una API existente de un servicio en la nube que haya desplegado que requiere que actualice el código.

Para obtener más información, consulte la sección 6.3 de Oracle PaaS and IaaS Public Cloud Services Pillar Document.

Todas las solicitudes de API de Oracle Cloud Infrastructure deben estar firmadas con fines de autenticación. Para obtener más información sobre las credenciales necesarias y cómo firmar las solicitudes, consulte Firmas de solicitud.

Todas las solicitudes de API de Oracle Cloud Infrastructure deben soportar el protocolo HTTPS y SSL TLS 1.2.

Las API de Oracle Cloud Infrastructure utilizan solicitudes y respuestas HTTP estándar. Cada una puede contener cabeceras específicas de Oracle para la paginación, etiquetas de entidad (ETags), etc., tal y como se describe en cualquier otra parte de este tema y de la documentación de API.

Cada respuesta incluye un ID de solicitud único asignado por Oracle (por ejemplo, bb3f3275-f356-462a-93c4-bf40fb82bb02) en la cabecera de respuesta opc-request-id. Si necesita contactar con Oracle por una solicitud concreta, indique este ID de solicitud.

Muchas de las operaciones de API necesitan JSON en el cuerpo de la solicitud o devuelven JSON en el cuerpo de la respuesta. El contenido específico de JSON se describe en la documentación de API para la operación individual. Tenga en cuenta que JSON no está ajustado ni etiquetado según el nombre de la operación o el tipo o nombre del objeto.

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 una solicitud da como resultado un error, la respuesta contiene un código de respuesta HTTP estándar con 4xx para errores de cliente y 5xx para errores de servidor. El cuerpo también incluye JSON con un código de error y una descripción del error. Por ejemplo:

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

Para obtener una lista de errores comunes en todos los servicios, consulte Errores de API.

Oracle Cloud Infrastructure aplica la limitación a muchas solicitudes de API para evitar el uso accidental o abusivo de los recursos. Si realiza demasiadas solicitudes muy rápidamente, puede que vea algunas correctas y otras que fallan. Oracle recomienda que implante una interrupción exponencial, empezando por unos segundos hasta un máximo de 60. Cuando una solicitud falla debido a la limitación, el sistema devuelve el código de respuesta 429 y el siguiente código de error y descripción:

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

La mayoría de los recursos de Oracle Cloud Infrastructure, como las instancias informáticas, tienen ciclos de vida. En muchos casos, desea que el código espere hasta que un recurso o una solicitud de trabajo lleguen a un estado específico, o se exceda el tiempo de espera, antes de realizar otras acciones.

Puede sondear un recurso para determinar su estado. Por ejemplo, cuando llama a GetInstance, el cuerpo de la respuesta contiene un recurso de instancia que incluye el atributo lifecycleState. Puede que desee que el código espere hasta que el elemento lifecycleState de la instancia se EJECUTE antes de continuar.

Los diferentes recursos tardan diferentes cantidades de tiempo en cambiar de un estado a otro. Por lo tanto, los parámetros de duración y frecuencia óptimos para una estrategia de sondeo pueden variar entre los recursos. Los procesos en espera de SDK de Oracle Cloud Infrastructure utilizan la siguiente estrategia por defecto:

• Usar una limitación exponencial, empezando por unos segundos hasta un máximo de 30 entre los intentos de sondeo.
• Sondear hasta 20 minutos y, a continuación, parar.

Para obtener más información sobre los procesos en espera, consulte:

• Documentación de los procesos en espera de SDK para Java
• Documentación de los procesos en espera de SDK para Ruby

Si utiliza la API, necesitará el OCID de su arrendamiento para firmar las solicitudes (consulte Firmas de solicitud). También lo necesitará para algunas de las operaciones de la API de IAM. Un OCID es un ID de Oracle Cloud (consulte Identificadores de recursos).

El OCID de arrendamiento tiene un aspecto similar a este (observe la palabra"tenancy" (arrendamiento) en él): ocid1.tenancy.oc1..<unique_ID>.

La mayoría de las operaciones de lista paginan los resultados. Por ejemplo, los resultados se paginan para la operación ListInstances en la API de servicios básicos. Al llamar a una operación de lista paginada, la respuesta indica más páginas de resultados al incluir la cabecera opc-next-page.

La paginación de lista de Object Storage ListObjects funciona de manera diferente porque los controles de paginación también se utilizan para filtrar nombres de objetos. ListObjects devuelve nextStartWith en lugar de opc-next-page en el cuerpo de la respuesta. Para paginar más objetos, utilice el valor nextStartWith devuelto con el parámetro start. Para filtrar los objetos que devuelve ListObjects, utilice los parámetros start y end.

En algunas operaciones, puede proporcionar un token de reintento único (opc-retry-token) para que se pueda reintentar la solicitud en caso de un error de tiempo de espera o de servidor sin el riesgo de volver a ejecutar esa misma acción. El token caduca después de 24 horas, pero se puede invalidar antes debido a las operaciones en conflicto (por ejemplo, si un recurso se ha suprimido y depurado del sistema, puede que se rechace un reintento de la solicitud de creación original).

La API soporta los ETags para fines de control de simultaneidad optimista. Las llamadas GET y POST devuelven una cabecera de respuesta etag con un valor que debería almacenar. Si posteriormente desea actualizar o suprimir el recurso, defina la cabecera if-match en el ETag que ha recibido para el recurso. El recurso se actualizará o suprimirá solo si el ETag que proporcione coincide con el valor actual del ETag de ese recurso.

Si envía una cadena vacía ("") como valor de un parámetro opcional, la API valida el valor como normal (por ejemplo, comprueba la longitud mínima y máxima permitida, etc.). A menudo la longitud mínima permitida es 1, por lo que se devolverá un error. Si no define el valor (es nulo), la API no realiza ninguna validación y puede que se produzcan otras acciones. Por ejemplo, si no define un valor para displayName al crear un nuevo objeto VCN, el servicio generará automáticamente un valor.