Diseño y edición de APIs

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Sigue las instrucciones de esta página a fin de usar Cloud Code para diseñar y editar APIs.

Roles adicionales necesarios para diseñar APIs

Necesitarás los roles que se indican a continuación para realizar algunos pasos de diseño y prueba de la API que se describen en esta página.

Tarea	Roles requeridos
Diseña APIs con Gemini Code Assist	Usuario de Gemini para Google Cloud Consumidor de Service Usage Consulta Otorga roles de IAM en un proyecto de Google Cloud para Gemini Code Assist.
Usa el contexto empresarial de tus APIs existentes en el concentrador de APIs cuando diseñas APIs.	Visualizador del concentrador de la API de Cloud
Registra tus APIs nuevas en el centro de APIs	Editor o administrador del concentrador de la API de Cloud
Edita las APIs del concentrador de la API en Cloud Code	Editor o administrador del concentrador de la API de Cloud
Configura y administra un servidor de simulación remoto para probar APIs	Administrador de Artifact Registry Cuenta de servicio de Cloud Build Administrador de Cloud Run Administrador de Service Usage Consulta la referencia de roles básicos y predefinidos de IAM.

Diseña APIs con Gemini Code Assist

Vista previa — Gemini Code Assist

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes usar Cloud Code para diseñar APIs de especificación de OpenAPI (OAS), versión 3.0 con Gemini Code Assist. Gemini Code Assist puede incluir contexto empresarial para la asistencia de IA generativa en el proceso de desarrollo de APIs. El contexto empresarial usa las APIs del concentrador de APIs del proyecto para el contexto cuando se generan APIs nuevas y solo está disponible con proyectos que usan el concentrador de APIs.

Consulta Cómo usar Gemini Code Assist si deseas obtener información sobre los pasos de configuración para usar la funcionalidad en esta sección.

Nota: En este momento, Gemini Code Assist admite el diseño de APIs que combinan objetos nuevos con objetos existentes (si el contexto empresarial está habilitado). No admite situaciones para la reutilización de objetos sin la creación de objetos nuevos.

Genera una API

Para generar una API, sigue estos pasos:

1. Haz clic en la varita mágica en el panel de navegación izquierdo para usar Gemini Code Assist y crear una nueva especificación de API. Asegúrate de usar este método para crear especificaciones de API en lugar del chat de Gemini Code Assist, que no admite todas las funciones y funcionalidades cuando se crean especificaciones de API.
   
2. Ingresa una instrucción que describa la API nueva en la ventana de entrada Crear una especificación de la API.
   1. Si lo deseas, selecciona una plantilla de instrucción de los chips de plantillas que se muestran. Una plantilla de instrucción proporciona un marco de trabajo para tu instrucción que te ayuda a comenzar.
   2. Ingresa una instrucción. Consulta Cómo escribir mensajes de especificaciones de API eficaces.
      
      
3. Gemini Code Assist genera un OAS que define la API.
4. Revisa la especificación:
   1. Haz clic en Ver código para revisar las especificaciones en el editor de código.
   2. En el panel del procesador de API, se muestra una vista previa de la API, ya que los desarrolladores pueden verla, incluida la descripción y otra documentación de la API.
   3. Si ya tienes APIs en el concentrador de APIs, ese contexto empresarial se usa para prepropagar objetos de otras APIs a este OAS y se enumeran en el panel OUTPUT:
      
   4. Agradecemos tus comentarios. Para enviar comentarios sobre las especificaciones generadas, haz clic en el ícono de pulgar hacia arriba o de pulgar hacia abajo en el panel de Swagger.
      
   5. Si deseas editar las instrucciones de vista previa y volver a generar la especificación, haz clic en las flechas del historial de instrucciones sobre las instrucciones para moverte entre las instrucciones anteriores.
      
5. Prueba la especificación: Una vez que se complete la nueva especificación, puedes probarla con un servidor de simulación. Consulta Prueba tu API con un servidor de simulación.
6. Haz clic en Guardar para guardar la API nueva con el nombre que elijas.
7. Para crear un proxy de API de Apigee a partir de esta especificación, haz clic en Crear proxy de API en el menú Más. El proceso de creación crea un paquete de proxy. Debería ver el nuevo proxy en la lista del menú de la izquierda de sus proxies. Consulta la explicación sobre la creación del proxy de API que está integrada en Cloud Code para obtener información adicional sobre la creación de proxies desde Cloud Code.
   

Cómo escribir mensajes de especificaciones de API eficaces

La exactitud y la idoneidad de una especificación de API generada dependen en gran medida de la instrucción que se proporcionó al modelo.

Estos son ejemplos de instrucciones buenas:

• Crea una API que permita a los clientes pagar un pedido mediante varias formas de pago, como tarjetas de crédito y débito.
• Acepta pedidos de compra para compras especializadas de granos de café a través de una API.
• Somos una empresa de pizzas y queremos crear una solución de entrega de pizza personalizada en línea. Crea una API para aceptar los pedidos de pizza.
• API para negocio de entrega de alimentos. Los clientes pueden pedir una combinación de pizza, hamburguesas o emparedados en un solo pedido. Cada uno de ellos tiene su propio esquema. Las pizzas tienen ingredientes y tamaño. Las hamburguesas tienen distintas variedades e ingredientes. Los emparedados tienen tipo de pan, tipo de carne, vegetales, queso y también instrucciones personalizadas.

En estos ejemplos, se muestran instrucciones menos eficaces. Evita los mensajes estructurados como los siguientes:

• Crea una API para mi tienda. Este mensaje contiene muy poca información para que el modelo genere una especificación completa y precisa.
• Crea una nueva API de reembolso que reutilice el objeto de pedido. No es necesario especificar qué objetos debe reutilizar Gemini Code Assist cuando creas APIs nuevas. Gemini Code Assist detecta automáticamente los objetos más adecuados para reutilizar.

Registra la API con el concentrador de API

Una vez que tu API se haya revisado y finalizado, puedes hacer que esté disponible para los desarrolladores mediante el registro en el concentrador de APIs:

1. Haz clic en Register to API Hub.
2. Sigue las indicaciones para registrar la API. Consulta Registra API para obtener información sobre cómo registrarte con el concentrador de API y la información que debes proporcionar.

Actualiza las APIs del concentrador de APIs desde Cloud Code

Puedes guardar una versión nueva de las especificaciones del concentrador de APIs cuando las edites desde Cloud Code.

Para guardar la especificación como una versión nueva, haz clic en el botón Más opciones... en el panel de Swagger y Publicar en el concentrador de APIs. Proporciona el ID de la versión de la API nueva. Deberías ver la versión nueva en la lista de versiones de esa API en la lista concentrador de APIs de Cloud Code.

Usa el archivo de configuración para controlar los comportamientos de Gemini Code Assist

En esta sección, se explica cómo administrar si Gemini Code Assist está disponible y de qué manera, desde el archivo de configuración.

Inhabilita o habilita Gemini Code Assist

Una vez que hayas configurado Apigee en Cloud Code (consulta Configura Apigee en Cloud Code), puedes agregar esta línea a tu archivo de configuración para inhabilitar de forma temporal todas las funciones de Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

Quita la línea o configúrala como true (el valor predeterminado) para volver a habilitar Gemini Code Assist.

Controla el contexto empresarial en la generación de especificaciones

La generación de OAS puede incluir esquemas, metadatos y definiciones de seguridad de las otras APIs de tu organización. El proceso encuentra APIs similares mediante los nombres y las descripciones de objetos en tu catálogo del concentrador de APIs que se encuentran en tu catálogo del concentrador de APIs al que tienes acceso. No se tiene en cuenta el estado de implementación de las APIs del concentrador de APIs.

El contexto empresarial está habilitado de forma predeterminada.

Puedes hacer lo siguiente:

• Consulta la cantidad de modificaciones incluidas en el contexto empresarial, si las hay, en el panel de Swagger:
• Consulta las modificaciones incluidas en el panel Resultado:

Si deseas inhabilitar el contexto empresarial para la generación de especificaciones nuevas, agrega estas líneas en el archivo settings.json después de "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }

Donde:

• enabled especifica si el contexto empresarial está habilitado en general. Configúralo como false para inhabilitar el contexto empresarial.
• includeMetadata controla si se incluye el contexto de metadatos. Este parámetro de configuración incluye o excluye los metadatos de otras APIs en el concentrador de APIs. includeMetadata solo es aplicable cuando enabled se configura como true.
• includeSchema controla si se incluye el contexto del esquema. Este parámetro de configuración incluye o excluye la información del esquema de otras APIs en el concentrador de APIs. includeSchema solo es aplicable cuando enabled se configura como true.
• includeSecurity controla si se incluye el contexto relacionado con la seguridad. Este parámetro de configuración incluye o excluye la información de seguridad de otras APIs en el concentrador de APIs. includeSecurity solo es aplicable cuando enabled se configura como true.

Edita APIs

Para usar Cloud Code a fin de editar las APIs existentes que forman parte de tu catálogo del concentrador de APIs, sigue estas instrucciones. Los cambios que realices en Cloud Code se pueden volver a guardar en el concentrador de APIs.

Estas instrucciones son para usuarios que no usan el complemento de Gemini Code Assist para Apigee. Para obtener información sobre la funcionalidad adicional que está disponible con Gemini Code Assist cuando diseñas y editas APIs, consulta Diseña una API con Gemini Code Assist.

Nota: En este momento, cualquier cambio en la API que se haya guardado de nuevo en el concentrador de APIs debe guardarse como una versión nueva.

Para editar una especificación de API, sigue estos pasos:

1. Asegúrate de que el proyecto que seleccionaste en Cloud Code sea el proyecto con el catálogo del concentrador de APIs que contiene la API que deseas editar.
2. En el panel de navegación izquierdo, expande el árbol Concentrador de APIs.
3. En la lista, selecciona la API y la versión que deseas editar.
4. Edita la especificación en el panel de edición. También puedes ver las operaciones de la API en el panel de Swagger.
5. De manera opcional, prueba tu API con un servidor de simulación.
6. Guarda los cambios como una versión nueva con el botón Más en el panel de Swagger y, luego, Publica en el concentrador de APIs. Confirma o actualiza la versión cuando se te solicite y vuelve a guardar los cambios en el concentrador de APIs. Deberías ver la versión nueva en la lista de versiones de esa API en la lista concentrador de APIs de Cloud Code.

Prueba tu API con un servidor de simulación

Puedes probar tu API con un servidor de simulación local o un servidor de simulación remoto basado en Google Cloud. El servidor de simulación local está instalado y disponible de forma predeterminada, mientras que debes configurar y administrar los servidores de simulación de Google Cloud.

Usa el servidor de simulación local

El servidor de simulación local acepta solicitudes a esta API y emula las respuestas. Solo el usuario actual puede usarlo durante la sesión actual. Sin embargo, a diferencia del servidor de simulación remota, no requiere configuración ni administración y no genera costos.

Nota: Es posible que el servidor de simulación local no funcione correctamente cuando se usa el Explorador remoto de VS Code. Además, en ocasiones, el servidor de simulación local no puede iniciarse. En ese caso, no estará disponible en la lista desplegable.

Para usar el servidor de simulación local, haz lo siguiente:

1. Selecciona el servidor de simulación local (servidor de desarrollo) en el menú desplegable Servidores.
   
2. Abre una ruta y haz clic en Probar.
   
3. Completa los parámetros de solicitud y haz clic en Ejecutar.
   
4. También puedes enviar solicitudes mediante curl desde un prompt. Usa la dirección y el puerto del servidor del menú desplegable Servidores.

Usa un servidor de simulación remoto

Un servidor de simulación remoto te permite crear una instancia de servidor de simulación persistente que, a diferencia del servidor de simulación local, puede compartirse y usarse para otros dentro de tu organización a fin de probar la API nueva antes de que esté disponible. producción. Los servidores de simulación remota solo se pueden usar con APIs registradas en el concentrador de APIs.

En este momento, se pueden crear servidores de simulación remota en Google Cloud. Los servidores de simulación remotos de Google Cloud no se actualizan automáticamente por ningún cambio que realices en la API después de implementar el servidor simulado, así que espera para agregar el servidor simulado hasta que hayas creado por completo la API.

La implementación de un servidor de simulación remoto de Google Cloud crea un nuevo servicio de Cloud Run. Compila una imagen de contenedor para el servidor de muestra con Cloud Build y la sube a Cloud Artifact Registry en tu proyecto de Google. eres responsable de cualquier costo resultante y mantenimiento de esos después de la creación. También eres responsable de borrarlas cuando ya no sean necesarias. Consulta ¿Qué es Cloud Run?, Administra servicios y la documentación de Artifact Registry.

Importante: Una vez que crees un servidor de simulación remota de Google Cloud, serás responsable de cualquier costo resultante de su uso, administrarlo y quitarlo cuando ya no sea necesario. Consulta https://cloud.google.com/run/pricing para obtener información sobre los precios, incluida la información sobre las opciones de niveles gratuitos.

Para implementar un servidor de simulación remoto, haz lo siguiente:

1. Selecciona Implementar servidor simulado (Google Cloud) en el menú Más.
2. Si tu API aún no está registrada en el concentrador de APIs, regístrala cuando se te solicite.
3. Especifica los detalles del servidor simulado remoto: ID del proyecto, Nombre del servidor y Región, y haz clic en Crear para crear el servidor simulado remoto.
   Importante: No crees varios servidores de simulación remota con el mismo nombre, aunque la interfaz de usuario no te impedirá hacerlo en este momento.
4. La generación de servidores de simulación remota requiere varios minutos. Puedes ver el progreso en el panel OUTPUT de Google Cloud.
5. Una vez que se complete la creación del servidor de simulación remoto, verás la URL del servidor remoto en la lista de servidores del panel de Swagger y el panel OUTPUT.
6. Para usar el servidor de simulación, abre una ruta y haz clic en Probar.
   
   
   Completa los parámetros de solicitud y haz clic en Ejecutar.
   
   
   También puedes enviar solicitudes mediante curl desde un prompt. Usa la dirección y el puerto del servidor del menú desplegable Servidores.

Para compartir el acceso al servidor simulado con otros usuarios, haz lo siguiente:

1. Otorga a otros usuarios la función de invocador para el servicio implementado. Consulta Autentica desarrolladores.
2. Cuando realizan la solicitud al servidor simulado, los usuarios siguen las instrucciones que se indican en Cómo probar tu servicio privado.

Sigue estos pasos para administrar los servidores de simulación remota implementados:

1. Ve al centro de APIs y busca la API para ver todas las implementaciones de la API, incluidos los servidores de simulación remota.
2. Usa la URL de recursos para ir a la implementación y administrarla. Para ello, detén, borra y realiza otras acciones en el servidor simulado.