Documentación de Oracle Cloud Infrastructure

Despliegue de una API en un gateway de API mediante la creación de un despliegue de API

Descubra cómo desplegar una API en un gateway mediante la creación de un despliegue con el servicio de gateway.

Tras crear un gateway de API, puede desplegar una API en él mediante la creación de un despliegue de API. Al crear un despliegue de API, se incluye una especificación de despliegue de API que define la API. El servicio de gateway de API inspecciona la especificación de despliegue de la API para confirmar que es válida.

Puede utilizar un único gateway de API como front-end para varios servicios de backend mediante:

  • Creación de un único despliegue de API en el gateway de API, con una especificación de despliegue de API que define varios servicios de backend.
  • Creación de varios despliegues de API en el mismo gateway de API, cada uno con una especificación de despliegue de API que define uno (o varios) servicios de backend.

Uso de la consola para crear un despliegue de API desde cero

Para utilizar la consola a fin de crear un despliegue de API, introduzca la especificación de despliegue de API en los cuadros de diálogo de la consola de la siguiente forma:

  1. En la página de lista Gateways, seleccione el gateway de API en el que desea desplegar la API. Si necesita ayuda para buscar la página de lista o el gateway de API, consulte Listado de gateways de API.
  2. En la página Detalles de puerta de enlace, seleccione Despliegues en la lista Recursos y, a continuación, Crear despliegue.

  3. Seleccione Desde cero y, en la sección Información básica, especifique:

    • Nombre: nombre del nuevo despliegue de API. Evite introducir información confidencial.

    • Prefijo de ruta de acceso: ruta de acceso en la que desplegar todas las rutas contenidas en la especificación de despliegue de API. Por ejemplo:

      • /v1
      • /v2
      • /test/20191122

      Tenga en cuenta que el prefijo de ruta de acceso de despliegue que especifique:

      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada única.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes), pero no debe terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • No puede incluir parámetros ni comodines.

      Tenga en cuenta también que si un despliegue de API tiene una sola barra inclinada como prefijo de ruta de acceso de despliegue, ese es el único despliegue de API permitido en un gateway de API determinado. No puede crear un despliegue de API con una sola barra inclinada como prefijo de ruta de acceso de despliegue si ya hay otro despliegue de API en el mismo gateway de API.

    • Compartimento: compartimento en el que se va a crear el nuevo despliegue de API.

  4. (Opcional) En la sección Políticas de solicitud de API, especifique opcionalmente los detalles de la política de solicitud a fin de proporcionar soporte para:

  5. (Opcional) En la sección Políticas de registro de API, especifique opcionalmente un nivel de log de ejecución para registrar información sobre el procesamiento en el gateway de API. Consulte Agregación de registro a despliegues de API.

  6. (Opcional) Seleccione Mostrar opciones avanzadas y, opcionalmente, especifique:

    • Etiquetas: si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a ese recurso. Free-form Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
  7. Seleccione Siguiente para mostrar la página Autenticación e introduzca los detalles de una política de solicitud de autenticación:

    Para obtener más información, consulte Adding Authentication and Authorization to API Deployments.

  8. Seleccione Siguiente para introducir detalles de las rutas en el despliegue de API.

  9. En la sección Ruta 1, especifique la primera ruta del despliegue de API que asigna una ruta de acceso y uno o varios métodos a un servicio de backend:

    • Ruta de acceso: ruta de acceso al servicio de backend para llamadas de API mediante los métodos enumerados. Tenga en cuenta que la ruta de acceso especificada:

      • Es relativa al prefijo de ruta de acceso de despliegue.
      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes) y puede terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • Puede incluir parámetros y comodines (consulte Agregación de parámetros de ruta y comodines a rutas de acceso).
    • Métodos: uno o más métodos aceptados por el servicio backend, separados por comas. Por ejemplo, GET, PUT.

    • Agregar un único backend o Agregar varios backends: indica si se deben enrutar todas las solicitudes al mismo backend o si se deben enrutar a diferentes backends según la variable de contexto y las reglas introducidas.

      En estas instrucciones se supone que desea utilizar un único backend, por lo que seleccione Agregar un único backend. Como alternativa, si desea utilizar diferentes backends, seleccione Agregar varios backends y siga las instrucciones de Uso de la consola para agregar una selección de backend dinámica a una especificación de despliegue de API.

    • Tipo de backend: tipo del servicio de backend, como uno de los siguientes:
  10. (Opcional) Seleccione Another Route para introducir detalles de rutas adicionales.
  11. Seleccione Siguiente para revisar los detalles introducidos para el nuevo despliegue de API.

  12. Seleccione Crear para crear el nuevo despliegue de API.

    Tenga en cuenta que la creación del nuevo despliegue de API puede tardar unos minutos. Mientras se crea, el despliegue de API se muestra en estado Creando en la página Detalles de gateway. Una vez que se ha creado correctamente, el nuevo despliegue de API se muestra en estado Activo.

    Tenga en cuenta también que, en lugar de crear el nuevo despliegue de API inmediatamente, puede crearlo más tarde mediante Resource Manager y Terraform, seleccionando Guardar como pila para guardar la definición de recurso como una configuración de Terraform. Para obtener más información sobre cómo guardar pilas de definiciones de recursos, consulte Creación de una pila a partir de una página de creación de recursos.

  13. Si el despliegue de API tarda demasiado en mostrarse en estado Activo (o si la operación de creación de despliegue de API ha fallado):

    1. Seleccione el nombre del despliegue de API y, a continuación, seleccione Solicitudes de trabajo para ver una visión general de la operación de creación de despliegue de API.
    2. Seleccione Crear despliegue para obtener más información sobre esta operación (incluidos los mensajes de error, los mensajes de log y el estado de los recursos asociados).
    3. Si la operación de creación de despliegue de API ha fallado y no puede diagnosticar la causa del problema a partir de la información de la solicitud de trabajo, consulte Solución de problemas de gateway de API.
  14. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Uso de la consola para crear un despliegue de API a partir de un archivo JSON

Para utilizar la consola a fin de crear un despliegue de API, cargue la especificación de despliegue de API desde un archivo JSON:

  1. En la página de lista Gateways, seleccione el gateway de API en el que desea desplegar la API. Si necesita ayuda para buscar la página de lista o el gateway de API, consulte Listado de gateways de API.
  2. En la página Detalles de puerta de enlace, seleccione Despliegues en la lista Recursos y, a continuación, Crear despliegue.
  3. Seleccione Cargar una API existente.

  4. En la sección Cargar información, especifique:

    • Nombre: nombre del nuevo despliegue de API. Evite introducir información confidencial.

    • Prefijo de ruta de acceso: ruta de acceso en la que desplegar todas las rutas contenidas en la especificación de despliegue de API. Por ejemplo:

      • /v1
      • /v2
      • /test/20191122

      Tenga en cuenta que el prefijo de ruta de acceso de despliegue que especifique:

      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada única.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes), pero no debe terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • No puede incluir parámetros ni comodines.
    • Compartimento: compartimento en el que se va a crear el nuevo despliegue de API.
    • Especificación: archivo JSON que contiene la especificación de despliegue de la API, puede arrastrar y soltar el archivo, o bien seleccionar Seleccionar uno. Consulte Creación de una especificación de despliegue de API.

    Tenga en cuenta también que si un despliegue de API tiene una sola barra inclinada como prefijo de ruta de acceso de despliegue, ese es el único despliegue de API permitido en un gateway de API determinado. No puede crear un despliegue de API con una sola barra inclinada como prefijo de ruta de acceso de despliegue si ya hay otro despliegue de API en el mismo gateway de API.

  5. (Opcional) Seleccione Mostrar opciones avanzadas y, opcionalmente, especifique:

    • Etiquetas: si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a ese recurso. Free-form Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
  6. Seleccione Siguiente para revisar los detalles introducidos para el nuevo despliegue de API.

  7. Seleccione Crear para crear el nuevo despliegue de API.

    Tenga en cuenta que la creación del nuevo despliegue de API puede tardar unos minutos. Mientras se crea, el despliegue de API se muestra en estado Creando en la página Detalles de gateway. Una vez que se ha creado correctamente, el nuevo despliegue de API se muestra en estado Activo.

    Tenga en cuenta también que, en lugar de crear el nuevo despliegue de API inmediatamente, puede crearlo más tarde mediante Resource Manager y Terraform, seleccionando Guardar como pila para guardar la definición de recurso como una configuración de Terraform. Para obtener más información sobre cómo guardar pilas de definiciones de recursos, consulte Creación de una pila a partir de una página de creación de recursos.

  8. Si el despliegue de API tarda demasiado en mostrarse en estado Activo (o si la operación de creación de despliegue de API ha fallado):

    1. Seleccione el nombre del despliegue de API y, a continuación, seleccione Solicitudes de trabajo para ver una visión general de la operación de creación de despliegue de API.
    2. Seleccione Crear despliegue para obtener más información sobre esta operación (incluidos los mensajes de error, los mensajes de log y el estado de los recursos asociados).
    3. Si la operación de creación de despliegue de API ha fallado y no puede diagnosticar la causa del problema a partir de la información de la solicitud de trabajo, consulte Solución de problemas de gateway de API.
  9. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Uso de la consola para crear un despliegue de API a partir de un recurso de API

Puede crear un despliegue de API a partir de un recurso de API existente, utilizando la descripción de la API del recurso de API. En este caso, la descripción de la API se basa en un archivo de descripción de la API que ha cargado para el recurso de API (consulte Creación de un recurso de API con una descripción de la API). El archivo de descripción de la API proporciona algunos valores iniciales para la especificación de despliegue de API que puede modificar y ampliar al crear el despliegue de API. En particular, se crea una ruta por defecto para cada ruta y método asociado en la descripción de la API.

Para utilizar la consola para crear un despliegue de API a partir de un recurso de API existente mediante una especificación de despliegue de API derivada de un archivo de descripción de la API:

  1. En la página de lista API, seleccione el nombre del recurso de API que desea desplegar. Si necesita ayuda para buscar la página de lista, consulte Listado de recursos de API.
  2. (Opcional) En la página Detalles de API, seleccione Especificación de despliegue de API de la lista Recursos para confirmar que se ha creado una especificación de despliegue de API válida para el recurso de API desde un archivo de descripción de la API cargado. Si no hay ninguna especificación de despliegue de API disponible, consulte Creación de un recurso de API con una descripción de la API
  3. En la página API Details, seleccione Deploy API Gateway para utilizar los cuadros de diálogo de la consola para crear un despliegue de la API.

    Algunos de los valores iniciales de las propiedades de especificación de despliegue de la API que se muestran en los cuadros de diálogo de la consola derivan del archivo de descripción de la API.

    En la sección Información de API se muestran detalles sobre el recurso de API a partir del que desea crear el despliegue de la API.

  4. En la sección Gateway, seleccione el gateway de API en el que desea crear el despliegue de la API. Si aún no existe un gateway de API adecuado, seleccione Crear gateway para crear uno (consulte Creación de un gateway de API).

  5. En la sección Información básica, especifique:

    • Nombre: nombre del nuevo despliegue de API. Evite introducir información confidencial.

    • Prefijo de ruta de acceso: ruta de acceso en la que desplegar todas las rutas contenidas en la especificación de despliegue de API.

      Por ejemplo:

      • /v1
      • /v2
      • /test/20191122

      Tenga en cuenta que el prefijo de ruta de acceso de despliegue que especifique:

      • Debe estar precedida de una barra inclinada (/) y puede ser simplemente esa barra inclinada única.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes), pero no debe terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • No puede incluir parámetros ni comodines.

      Tenga en cuenta también que si un despliegue de API tiene una sola barra inclinada como prefijo de ruta de acceso de despliegue, ese es el único despliegue de API permitido en un gateway de API determinado. No puede crear un despliegue de API con una sola barra inclinada como prefijo de ruta de acceso de despliegue si ya hay otro despliegue de API en el mismo gateway de API.

    • Compartimento: compartimento en el que se va a crear el nuevo despliegue de API.

  6. (Opcional) En la sección Políticas de solicitud de API, especifique opcionalmente los detalles de la política de solicitud a fin de proporcionar soporte para:

  7. (Opcional) En la sección Políticas de registro de API, especifique opcionalmente un nivel de log de ejecución para registrar información sobre el procesamiento en el gateway de API. Consulte Agregación de registro a despliegues de API.

  8. (Opcional) Seleccione Mostrar opciones avanzadas y, opcionalmente, especifique:

    • Etiquetas: si tiene permisos para crear un recurso, también tiene permisos para aplicar etiquetas de formato libre a ese recurso. Free-form Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.

  9. Seleccione Siguiente para revisar e introducir detalles de las rutas en el despliegue de API.

    Por defecto, se crea una ruta para cada ruta y método asociado que está presente en la descripción de la API. Inicialmente, cada una de estas rutas por defecto se crea con un backend de respuesta de stock. El código de estado HTTP, el contenido del cuerpo del contenido del cuerpo de respuesta y la cabecera se obtienen de los detalles de la descripción de la API. Si la descripción de la API no incluye información de respuesta para una ruta concreta y un método asociado, se crea un backend de respuesta de stock por defecto para esa ruta con 501 como código de estado HTTP.

  10. Revise cada ruta por defecto una por una y modifique su configuración si es necesario para cumplir sus requisitos. Agregue políticas de solicitud, respuesta y registro:

  11. (Opcional) Seleccione Otra ruta para introducir detalles de más rutas, además de las creadas por defecto a partir de la descripción de la API.
  12. Seleccione Siguiente para revisar los detalles introducidos para el nuevo despliegue de API.

  13. Seleccione Crear para crear el nuevo despliegue de API.

    Tenga en cuenta que la creación del nuevo despliegue de API puede tardar unos minutos. Mientras se crea, el despliegue de API se muestra en estado Creando en la página Detalles de gateway. Una vez que se ha creado correctamente, el nuevo despliegue de API se muestra en estado Activo.

  14. Si el despliegue de API tarda demasiado en mostrarse en estado Activo (o si la operación de creación de despliegue de API ha fallado):

    1. Seleccione el nombre del despliegue de API y, a continuación, seleccione Solicitudes de trabajo para ver una visión general de la operación de creación de despliegue de API.
    2. Seleccione Crear despliegue para obtener más información sobre esta operación (incluidos los mensajes de error, los mensajes de log y el estado de los recursos asociados).
    3. Si la operación de creación de despliegue de API ha fallado y no puede diagnosticar la causa del problema a partir de la información de la solicitud de trabajo, consulte Solución de problemas de gateway de API.
  15. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Uso de la CLI

Para crear una nueva implementación de API mediante la CLI:

  1. Configure su entorno de cliente para usar la CLI ( Configuración del entorno de cliente para utilizar la CLI para el desarrollo de gateway de API).

  2. Abra un símbolo del sistema y ejecute oci api-gateway deployment create para crear el despliegue:

    oci api-gateway deployment create --compartment-id <compartment-ocid> --display-name <api-name> --gateway-id <gateway-ocid> --path-prefix "/<deployment-path-prefix>" --specification file:///<filename>

    donde:

    • <compartment-ocid> es el OCID del compartimento en el que se creará el nuevo despliegue de API.
    • <api-name> es el nombre del nuevo despliegue de API. Evite introducir información confidencial.
    • <gateway-ocid> es el OCID del gateway existente en el que se desplegará la API. Para conocer el OCID del gateway de API, consulte Enumeración de gateways de API.

    • /<deployment-path-prefix> es una ruta de acceso en la que desplegar todas las rutas incluidas en la especificación de despliegue de API.

      Tenga en cuenta que el prefijo de ruta de acceso de despliegue que especifique:

      • Debe estar precedida por una barra inclinada (/) en el archivo JSON y puede ser solo esa barra inclinada.
      • Puede contener varias barras inclinadas (siempre que no sean adyacentes), pero no debe terminar con una barra inclinada.
      • Puede incluir caracteres alfanuméricos en mayúscula y minúscula.
      • Puede incluir los caracteres especiales $ - _ . + ! * ' ( ) , % ; : @ & = .
      • No puede incluir parámetros ni comodines.

      Tenga en cuenta también que si un despliegue de API tiene una sola barra inclinada como prefijo de ruta de acceso de despliegue, ese es el único despliegue de API permitido en un gateway de API determinado. No puede crear un despliegue de API con una sola barra inclinada como prefijo de ruta de acceso de despliegue si ya hay otro despliegue de API en el mismo gateway de API.

    • <filename> es la especificación de despliegue de API, que incluye una ruta de acceso, uno o varios métodos y una definición de backend. Consulte Creación de una especificación de despliegue de API.

    Por ejemplo:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json

    La respuesta al comando incluye:

    • El OCID del despliegue de API.

    • Nombre de host en el que se ha creado el despliegue de API, como un nombre de dominio con el formato <gateway-identifier>.apigateway.<region-identifier>.oci.customer-oci.com, donde:

      • <gateway-identifier> es la cadena de caracteres que identifica el gateway de API. Por ejemplo, lak...sjd (abreviado para lectura).
      • <region-identifier> es el identificador de la región en la que se ha creado el despliegue de API. Consulte Disponibilidad por región.

      Por ejemplo, lak...sjd.apigateway.us-phoenix-1.oci.customer-oci.com.

      El nombre de host será el nombre de dominio que se utilizará al llamar a una API desplegada en el gateway de API.

    • Estado del ciclo de vida (por ejemplo, ACTIVE, FAILED).
    • ID de la solicitud de trabajo para crear el despliegue de la API (los detalles de las solicitudes de trabajo están disponibles durante siete días tras la finalización, cancelación o fallo).

    Si desea que el comando espere para devolver el control hasta que el despliegue de la API esté activo (o que la solicitud haya fallado), incluya uno o los dos parámetros siguientes:

    • --wait-for-state ACTIVE
    • --wait-for-state FAILED

    Por ejemplo:

    oci api-gateway deployment create --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --display-name "Marketing Deployment" --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --path-prefix "/marketing" --specification file:///Users/jdoe/work/deployment.json --wait-for-state ACTIVE

    Tenga en cuenta que no puede utilizar el despliegue de API hasta que la solicitud de trabajo lo haya creado correctamente y el despliegue de API esté activo.

  3. (Opcional) Para ver el estado del despliegue de API, introduzca:

    oci api-gateway deployment get --deployment-id <deployment-ocid>

  4. (Opcional) Para ver el estado de la solicitud de trabajo que está creando el despliegue de API, introduzca:

    oci api-gateway work-request get --work-request-id <work-request-ocid>

  5. (Opcional) Para ver los logs de la solicitud de trabajo que está creando el despliegue de API, introduzca:

    oci api-gateway work-request-log list --work-request-id <work-request-ocid>

  6. (Opcional) Si falla la solicitud de trabajo que está creando el despliegue de API y desea revisar los logs de errores, introduzca:

    oci api-gateway work-request-error --work-request-id <work-request-ocid>

Para obtener más información sobre el uso de la CLI, consulte Interfaz de línea de comandos (CLI). Para obtener una lista completa de los indicadores y las opciones disponibles para los comandos de la CLI, consulte Ayuda de CLI.