API de REST

Las API de Oracle Cloud Infrastructure son API de REST típicas que utilizan solicitudes y respuestas HTTPS. En este tema se describe información básica sobre el uso de las API.

Puntos finales y referencia de API

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.

Versión 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

Política de nuevos cambios de API

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.

Firma de solicitud necesaria

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.

Se necesita HTTPS y TLS 1.2

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

Máximo sesgo de reloj del cliente permitido

Se devuelve el código de estado de HTTP 401 (No autenticado) si el reloj del cliente está sesgado más de 5 minutos respecto al servidor. Para determinar la hora del reloj del servidor, use este comando curl con el punto final de API:

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

Por ejemplo:

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

Formato de solicitud y respuesta

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.

Nota

Asegúrese de definir la cabecera Content-Type en application/json en las solicitudes POST y PUT que contengan JSON en el cuerpo.

Solicitud CreateVcn de ejemplo


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

Respuesta CreateVcn de ejemplo

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

Formato de error

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.

Limitación de solicitudes

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

Sondeo del estado de los recursos

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:

Dónde encontrar el OCID del arrendamiento

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

Lo puede encontrar en la consola de Oracle Cloud Infrastructure en la página Detalles de arrendamiento:

  1. Abra el menú Perfil (Icono de menú de usuario) y haga clic en Arrendamiento: <your_tenancy_name>.

  2. El OCID de arrendamiento se muestra en Información de arrendamiento. Haga clic en Copiar para copiarlo en el portapapeles.

    Página Detalles de arrendamiento que muestra la ubicación del OCID de arrendamiento

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

Paginación de lista

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.

Nota

Una página puede estar vacía incluso cuando permanecen más resultados. Cada vez que aparece la cabecera opc-next-page, hay más elementos de lista que obtener. Para obtener más información sobre el control de la lista de recursos, consulte Visión general de búsqueda.

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.

Para obtener la siguiente página de resultados

Realice una nueva solicitud GET en la misma URL, modificada al definir el parámetro de consulta de página en el valor de la cabecera opc-next-page. Repita este proceso hasta que obtenga una respuesta sin una cabecera opc-next-page. La ausencia de esta cabecera indica que ha alcanzado la última página de la lista.

Nota

Para obtener una alternativa a la escritura de código de paginación, consulte las funciones en el módulo de paginación proporcionado con el SDK para Python.
Para obtener la página anterior de resultados
(Disponible con algunas API). Realice una nueva solicitud GET en la misma URL, modificada al definir el parámetro de consulta de página en el valor de la cabecera opc-prev-page. Repita este proceso hasta que obtenga una respuesta sin una cabecera opc-prev-page. La ausencia de esta cabecera indica que ha alcanzado la primera página de la lista.
Nota

Para obtener una alternativa a la escritura de código de paginación, consulte las funciones en el módulo de paginación proporcionado con el SDK para Python.
Para cambiar el número máximo de resultados por página

En la solicitud GET, defina el límite del número de elementos que desea que se devuelvan en la respuesta.

Nota

El servicio no devolverá más del número especificado como límite, pero puede que no devuelva ese número exacto.

Token de reintento

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

ETags para control de simultaneidad optimista

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.

Cadenas nulas frente a vacías para parámetros opcionales

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.