Descripción general

Una especificación de OpenAPI usa un formato estándar para describir una API de RESTful. Una especificación de OpenAPI, que está escrita en formato JSON o YAML, es legible por máquinas, pero también es fácil de leer y comprender.

La especificación describe elementos de una API, incluidos su ruta base, rutas de recursos y verbos, operaciones, encabezados, parámetros de consulta y respuestas. Además, una especificación de OpenAPI se suele usar para generar documentación de la API.

En este lab, examinarás una especificación de OpenAPI para un servicio de backend de venta minorista. Luego, usarás esta especificación de OpenAPI para crear un proxy de API que se usará para agregar funciones y seguridad a la API de backend.

Objetivos

En este lab, aprenderás a realizar las siguientes tareas:

• Explorar una especificación de OpenAPI y comprender los diferentes componentes
• Crear un proxy de API a partir de una especificación de OpenAPI con el asistente de proxy
• Realizar un seguimiento de un proxy de API

Configuración

En cada lab, recibirás un proyecto de Google Cloud y un conjunto de recursos nuevos por tiempo limitado y sin costo adicional.

1. Accede a Google Skills en una ventana de incógnito.

2. Ten en cuenta el tiempo de acceso del lab (por ejemplo, 1:15:00) y asegúrate de finalizarlo en el plazo asignado. No existe una función de pausa. Si lo necesitas, puedes reiniciar el lab, pero deberás hacerlo desde el comienzo.

3. Cuando tengas todo listo, haz clic en Comenzar lab.

4. Anota las credenciales del lab (el nombre de usuario y la contraseña). Las usarás para acceder a la consola de Google Cloud.

5. Haz clic en Abrir la consola de Google.

6. Haz clic en Usar otra cuenta, copia las credenciales para este lab y pégalas en el mensaje emergente que aparece. Si usas otras credenciales, se generarán errores o incurrirás en cargos.

7. Acepta las condiciones y omite la página de recursos de recuperación.

Activa Google Cloud Shell

Google Cloud Shell es una máquina virtual que cuenta con herramientas para desarrolladores. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud.

Google Cloud Shell proporciona acceso de línea de comandos a tus recursos de Google Cloud.

1. En la consola de Cloud, en la barra de herramientas superior derecha, haz clic en el botón Abrir Cloud Shell.

   

2. Haz clic en Continuar.

El aprovisionamiento y la conexión al entorno demorarán unos minutos. Cuando te conectes, habrás completado la autenticación, y el proyecto estará configurado con tu PROJECT_ID. Por ejemplo:

gcloud es la herramienta de línea de comandos de Google Cloud. Viene preinstalada en Cloud Shell y es compatible con el completado de línea de comando.

• Puedes solicitar el nombre de la cuenta activa con este comando:

gcloud auth list

Resultado:

Credentialed accounts: - @.com (active)

Resultado de ejemplo:

Credentialed accounts: - google1623327_student@qwiklabs.net

• Puedes solicitar el ID del proyecto con este comando:

gcloud config list project

Resultado:

[core] project =

Resultado de ejemplo:

[core] project = qwiklabs-gcp-44776a13dea667a6 Nota: La documentación completa de gcloud está disponible en la guía de descripción general de gcloud CLI .

Tarea 1: Examina la especificación de OpenAPI para el servicio de backend

En esta tarea, explorarás la especificación de OpenAPI que se creó para un servicio de backend que usarás en tus proxies de API.

Descarga la especificación de OpenAPI

• En Cloud Shell, descarga la especificación de OpenAPI para el servicio de backend con este comando de curl:

  curl https://storage.googleapis.com/cloud-training/developing-apis/specs/retail-backend.yaml?$(date +%s) --output ~/retail-backend.yaml

  Este comando de curl descarga un archivo llamado retail-backend.yaml y lo almacena en un archivo con el mismo nombre en el directorio principal. Más adelante en el lab, usarás esta misma especificación cuando crees un proxy de API.

  Nota: "?$(date +%s)" agrega un parámetro de consulta a la URL que es una representación de cadena de la fecha y hora actuales. Esta variable que cambia de forma dinámica modifica la URL y obliga a curl a recuperar la versión más reciente de un archivo, incluso si se almacenó en caché una versión anterior.

Consulta la especificación de OpenAPI en el Editor de Cloud Shell

1. En Cloud Shell, haz clic en Abrir editor.

   

2. En el editor, selecciona el archivo retail-backend.yaml.

   

Explora las secciones de la especificación

1. Examina la especificación de OpenAPI.

   Esta es la especificación de OpenAPI para el servicio de backend que se usará en muchos de los labs del curso. Exploremos sus secciones.

   El campo openapi define la versión de la especificación. Esta es una especificación de OpenAPI versión 3, como se indica en el número de versión en la parte superior del archivo:

   openapi: "3.0.0"

   El objeto info proporciona metadatos sobre la API en sí. La versión que se muestra es la de la especificación de Retail Backend:

   info: version: 1.0.0 title: Retail Backend description: Retail backend database used for Developing APIs course contact: name: Google Cloud (Apigee) email: apigee@example.org url: https://cloud.google.com/apigee license: name: MIT url: https://opensource.org/licenses/MIT

   El array servers contiene una lista de objetos de servidor que especifican información de conectividad para los servidores de destino. Esta especificación contiene un único servicio de backend, al que llamará tu proxy de API:

   servers: - url: "https://gcp-cs-training-01-test.apigee.net/training/db" description: Retail backend for Developing APIs course

   El array tags agrega metadatos a las etiquetas que se usan en las operaciones, que se muestran a continuación. Las etiquetas pueden compartirse entre varias operaciones y pueden usarse para proporcionar descripciones detalladas o vínculos a documentación externa.

   tags: - name: categories description: Product Categories - name: products description: Products - name: orders description: Orders - name: stores description: Stores

   El objeto paths contiene las rutas relativas a los extremos individuales y sus operaciones. Una de esas rutas, /categories/{categoryId}, se usa para especificar una sola categoría. Aquí se muestra una operación get especificada para obtener una categoría por ID. El objeto get muestra parámetros y respuestas. Para las operaciones que contienen un cuerpo de solicitud, como PATCH /products/{productId}, también se especificará el cuerpo de la solicitud.

   /categories/{categoryId}: get: summary: Get a specific category operationId: getCategoryById tags: - categories parameters: - name: categoryId in: path required: true description: category id schema: type: integer responses: '200': description: Selected category content: application/json: schema: $ref: "#/components/schemas/Category" '404': description: Category not found content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error"

   El objeto components contiene objetos reutilizables para diferentes partes de la especificación de OpenAPI. El objeto del componente securitySchemes contiene definiciones de diferentes tipos de esquemas de seguridad que usan las operaciones. Esta especificación define un esquema de autenticación básico único, al que se hace referencia en la operación PATCH /products/{productId}. El objeto de componente schemas contiene tipos de datos de entrada y salida. Aquí se muestra el objeto Category, que se devuelve cuando la operación GET /categories/{categoryId} se realiza correctamente:

   components: securitySchemes: basicAuth: type: http description: basic auth scheme: basic schemas: Category: type: object description: product category required: - color - id - name properties: color: description: use this color for displaying this category type: string id: description: integer id (used for access) type: integer format: int32 minimum: 0 name: description: category name type: string

   No dudes en explorar la especificación o la documentación de la especificación de OpenAPI.

2. Para obtener más detalles sobre esta especificación de OpenAPI, usa el panel de Gemini Code Assist en el editor. Expande el elemento de contexto en la sección Instrucciones y confirma que el archivo actual retail-backend.yaml esté seleccionado.

3. En la instrucción, escribe lo siguiente:

   Explain the contents of this file.

4. Haz clic en Enviar ().

   Gemini genera una respuesta que describe el contenido de la especificación de OpenAPI de backend. Se incluye un resumen de alto nivel y secciones clave que explican el propósito de las secciones definidas.

Descarga la especificación de OpenAPI en tu máquina

1. Haz clic en Abrir terminal.

2. Selecciona el menú Más () de Cloud Shell y, luego, haz clic en Descargar.

3. Ingresa retail-backend.yaml y, luego, haz clic en Descargar.

   Esta acción descargará el archivo en tu máquina local.

Tarea 2: Crea un proxy de API con la especificación de OpenAPI

En esta tarea, crearás un proxy de API con la especificación de OpenAPI para el servicio de backend.

Fija la página de la consola de Apigee

1. En el menú de navegación () de la consola de Google Cloud, busca Apigee en la sección Productos favoritos.

   Se abrirá la página de la consola de Apigee.

2. Si Apigee no aparece en la lista, búscalo en la barra de búsqueda superior y navega al servicio Apigee.

3. Para fijar Apigee en la consola, haz clic en el ícono de favoritos ().

   La página de la consola de Apigee ahora aparecerá como un producto favorito en el menú de navegación.

Usa el asistente de proxy para crear un proxy

1. En el menú de navegación de la izquierda, selecciona Desarrollo de proxies > Proxies de API.

2. Para iniciar el asistente de proxy, haz clic en + Crear.

3. En Proxy template, selecciona OpenAPI spec template > Reverse proxy (Most common).

4. En OpenAPI specs, haz clic en Browse, selecciona el archivo retail-backend.yaml que descargaste y, luego, haz clic en Open.

5. Haz clic en Next.

6. Especifica lo siguiente para los detalles del proxy:

   Propiedad	Valor
   Nombre del proxy	retail-v1
   Ruta de acceso base	/retail/v1
   Descripción	My retail API

   El destino se tomó del array servers en la especificación de OpenAPI. Deja el destino sin cambios.

   Nota: Confirma que estás usando "/retail/v1" para la ruta de acceso base, no "/retail-v1".

7. Haz clic en Siguiente.

   Se enumeran las operaciones que se encontraron en la especificación de OpenAPI.

8. En los flujos, en la fila del encabezado, haz clic en Seleccionar todas las filas.

   Ahora deberían estar seleccionados todos los flujos.

9. Haz clic en Siguiente.

10. En Deployment environments, selecciona el entorno eval y, luego, haz clic en ACEPTAR.

    Nota: Deja el campo "Cuenta de servicio" vacío.

11. Haz clic en Crear.

    Se generará tu proxy y se marcará para implementarlo.

Es posible que se retrase la disponibilidad del entorno de ejecución

Las organizaciones de Apigee suelen tardar 30 minutos o más en aprovisionarse por completo. La mayor parte del tiempo se dedica a aprovisionar el clúster del entorno de ejecución, la base de datos del entorno de ejecución y los servicios que se usan para ejecutar tus proxies de API. Cuando se crea una organización de Apigee de larga duración, esta demora en el aprovisionamiento completo no es un problema, pero no deberías tener que esperar media hora antes de comenzar cada lab.

En ocasiones, verás que la organización ya está completamente aprovisionada cuando ingreses al lab. En otras, la organización de Apigee solo comenzará el aprovisionamiento cuando inicies el lab.

Las operaciones del plano de administración de la organización están disponibles después de unos minutos del proceso de aprovisionamiento. En vez de esperar a que el entorno de ejecución se aprovisione por completo, estos labs permiten realizar operaciones como editar el proxy antes de que el entorno de ejecución esté disponible. Cuando implementas un proxy en un entorno antes de que el entorno de ejecución esté disponible, no podrá recibir tráfico hasta que se complete el aprovisionamiento del entorno de ejecución.

Cuando mantienes el puntero sobre el ícono Estado de un proxy implementado, como se muestra a continuación, tal vez veas que no hay instancias que informen el estado. Esto es normal hasta que se aprovisione por completo el entorno de ejecución de la organización de Apigee.

Obtén más información sobre la implementación de proxies de Apigee

Para obtener información sobre el proceso de implementación de un proxy de API en un entorno de Apigee, puedes usar Gemini Cloud Assist en la consola de Google Cloud.

Abre Gemini Cloud Assist

1. Para abrir Gemini Cloud Assist, en la consola de Google Cloud, haz clic en Abrir o cerrar el chat de Gemini Cloud Assist ().

2. Si se te solicita en el panel de Cloud Assist, haz clic en Obtener Gemini Cloud Assist.

3. De manera opcional, puedes ver las APIs que se requieren y recomiendan habilitar.

4. Haz clic en Enable Gemini Cloud Assist at no cost.

5. Haz clic en Empezar a chatear.

Envía instrucciones a Gemini

1. En la instrucción, escribe lo siguiente:

   In Apigee X, explain the deployment process of an API proxy to an Apigee environment.

2. Haz clic en Enviar ().

   Lee la respuesta generada por Gemini Cloud Assist.

3. De manera opcional, haz clic en Mostrar contenido relacionado para explorar la documentación sobre el tema.

Comprueba el estado de la implementación

Un proxy que está implementado y listo para recibir tráfico se mostrará con un estado de color verde en la pestaña Descripción general.

Cuando un proxy se marca como implementado, pero el entorno de ejecución aún no está disponible y el entorno aún no está conectado, es posible que veas un signo de advertencia rojo. Mantén el puntero sobre el ícono de Estado para ver el estado actual.

Si el proxy se implementó y aparece en verde, significa que está listo para el tráfico de APIs. Si tu proxy no se implementó porque no hay Pods de entorno de ejecución, puedes verificar el estado de aprovisionamiento.

Verifica el estado de aprovisionamiento

• Para confirmar que se instaló la instancia de entorno de ejecución y que se conectó el entorno de evaluación, ejecuta los siguientes comandos en Cloud Shell:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***"; Estos comandos usan la API de Apigee para determinar cuándo se creó la instancia de entorno de ejecución y cuándo se conectó el entorno de evaluación a la instancia. Puedes copiar este comando en Cloud Assist si quieres que Gemini explique cómo funcionan los comandos.

  Cuando la secuencia de comandos devuelva el mensaje ORG IS READY TO USE, podrás continuar con los próximos pasos.

Mientras esperas

• Web API Design: The Missing Link, un libro electrónico sobre los principios de diseño de APIs
• Especificación de OpenAPI

Tarea 3: Explora y haz un seguimiento del proxy de API

Inicia la herramienta de depuración

1. Selecciona la pestaña Desarrollo.

   Esta pestaña se usa para editar el proxy que se generó. Se crearon flujos condicionales para cada una de las operaciones en la especificación de OpenAPI. Estos flujos condicionales aparecen en el extremo del proxy en el navegador de la izquierda. Cuando haces clic en un flujo condicional, sus secciones de solicitud y respuesta se seleccionan en el panel del editor visual. El código default.xml que se muestra a continuación es la representación del código de los flujos de extremos de proxy.

   

   Actualizarás muchos de estos flujos condicionales en labs posteriores.

2. Selecciona la pestaña Depuración.

   La herramienta de depuración se usa para rastrear las solicitudes a APIs que maneja el proxy.

3. Haz clic en Inicia la sesión de depuración.

4. En el panel Inicia la sesión de depuración, en el menú desplegable Entorno, selecciona eval.

   El número de revisión implementada también se mostrará en el menú desplegable.

5. Haz clic en Iniciar.

   La sesión de depuración se ejecutará durante 10 minutos.

Prueba el proxy de API con el DNS privado

Se puede llamar al entorno de evaluación en la organización de Apigee con el nombre de host eval.example.com. La entrada de DNS para este nombre de host se creó dentro de tu proyecto y se resuelve en la dirección IP de la instancia de entorno de ejecución de Apigee. Esta entrada de DNS se creó en una zona privada, lo que significa que solo es visible en la red interna.

Cloud Shell no reside en la red interna, por lo que los comandos de Cloud Shell no pueden resolver esta entrada de DNS. Una máquina virtual (VM) dentro de tu proyecto puede acceder al DNS de la zona privada. Se creó automáticamente una máquina virtual llamada apigeex-test-vm para este propósito. Puedes realizar llamadas al proxy de API desde esta máquina.

El comando curl se usará para enviar solicitudes a un proxy de API. La opción -k de curl indica que debe omitir la verificación del certificado TLS. En este lab, el entorno de ejecución de Apigee usa un certificado autofirmado. Para un entorno de producción, debes usar certificados creados por una autoridad certificadora (CA) de confianza.

1. En Cloud Shell, abre una pestaña nueva y, luego, abre una conexión SSH a tu VM de prueba:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   El primer comando de gcloud recupera la zona de la VM de prueba y el segundo abre la conexión SSH a la VM.

2. Si se te solicita, escribe Y para continuar.

   Para cada pregunta que se haga en Cloud Shell, presiona Intro o Retorno para especificar la entrada predeterminada.

   La identidad con la que accediste es la propietaria del proyecto, por lo que se permite la conexión SSH a esta máquina.

   Tu sesión de Cloud Shell ahora se ejecuta dentro de la VM.

Llama al proxy de API

1. Para hacer una llamada al proxy alojado en el entorno eval, en la sesión de SSH de Cloud Shell, envía una solicitud a tu proxy de API con este comando:

   curl -i -k -X GET https://eval.example.com/retail/v1/categories

   Una transacción para esta solicitud debería aparecer en el panel Transacciones de la izquierda. Cuando se selecciona una transacción, verás un seguimiento de la solicitud y la respuesta a través de Apigee. Deberías ver un código de estado 200 si tu URL de backend se configuró correctamente y actualizaste la URL de envío de solicitudes de forma correcta.

   Nota: El tráfico de la sesión de depuración de Apigee se recupera a través de un sondeo asíncrono de nuevas llamadas a la API, por lo que puede haber un retraso entre el momento en que se completa una solicitud a la API y el momento en que se muestra en la herramienta de depuración.

2. Haz clic en los botones Atrás y Siguiente para navegar por los pasos de la transacción.

   La solicitud fue GET /retail/v1/categories. Esta solicitud se envió al backend, que respondió con un array JSON que contenía las categorías.

¡Felicitaciones!

En este lab, aprendiste sobre las especificaciones de OpenAPI y exploraste algunas de las funciones en las especificaciones. Usaste una especificación de OpenAPI para un servicio de backend de venta minorista para crear un proxy de API y rastreaste llamadas a través de ese proxy.

Finaliza el lab

Cuando hayas completado el lab, haz clic en Finalizar lab. Google Skills quitará los recursos que usaste y limpiará la cuenta.

Tendrás la oportunidad de calificar tu experiencia en el lab. Selecciona la cantidad de estrellas que corresponda, ingresa un comentario y haz clic en Enviar.

La cantidad de estrellas indica lo siguiente:

• 1 estrella = Muy insatisfecho
• 2 estrellas = Insatisfecho
• 3 estrellas = Ni satisfecho ni insatisfecho
• 4 estrellas = Satisfecho
• 5 estrellas = Muy satisfecho

Puedes cerrar el cuadro de diálogo si no deseas proporcionar comentarios.

Para enviar comentarios, sugerencias o correcciones, usa la pestaña Asistencia.

Copyright 2026 Google LLC. Todos los derechos reservados. Google y el logotipo de Google son marcas de Google LLC. El resto de los nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que están asociados.