Compila un proxy de API simple

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

Consulta la documentación de Apigee Edge.

Nota: En los entornos habilitados para implementaciones de archivos, no puedes compilar proxies de API mediante la IU de Apigee, la API o gcloud. Si deseas compilar proxies de API para implementaciones de archivos mediante Apigee en VS Code, consulta Desarrolla proxies de API mediante Apigee en VS Code.

Apigee le permite exponer rápidamente servicios de backend como API. Esto se logra mediante la creación de un proxy de API que proporciona una fachada para el servicio de backend que deseas exponer. Solo necesita proporcionar la dirección de la red del servicio de backend, además de cierta información que Apigee usa para crear el proxy de API que se expone a los desarrolladores.

El proxy de API separa la implementación de tu servicio de backend de la API que consumen los desarrolladores. Esto protege a los desarrolladores de futuros cambios a sus servicios de backend. Mientras actualizas los servicios de backend, los desarrolladores, aislados de esos cambios, pueden continuar llamando a la API sin interrupciones.

En este tema, se proporciona información sobre los distintos tipos de proxies y la configuración para ellos. Para obtener instrucciones paso a paso sobre cómo crear proxies, consulta los siguientes temas:

• Instructivo: Compila tu primer proxy de API.
• Crea un proxy de API

Nota: En el siguiente video, se muestra el Editor de proxies clásico en la IU de Apigee. Apigee presenta una versión nueva del Editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en el video.

Crea un proxy de API mediante la IU

La manera más sencilla de crear un proxy de API es mediante el asistente de Creación de proxy.

Para acceder al asistente de Creación de proxy con la IU de Apigee, sigue estos pasos:

1. Accede a la IU de Apigee.
2. En la barra de navegación, selecciona Desarrollar > Proxies de API.
3. Haz clic en Crear nuevo.
   

Aparecerá el asistente de Creación de proxy y te guiará por los pasos necesarios para generar y agregar funciones mínimas a un proxy de API.

La primera página del asistente te permite crear un proxy de API de las siguientes fuentes:

Tipo	Descripción
Proxy inverso (más común)	Es un proxy de API que enruta las solicitudes entrantes a servicios de backend HTTP existentes. Puede ser una API JSON o XML. Consulta Crea un proxy inverso para un servicio HTTP más adelante en esta sección. Haz clic en Usar una especificación de OpenAPI para generar el proxy a partir de una especificación de OpenAPI válida. Si deseas obtener más información sobre esta opción, consulta Usa especificaciones de OpenAPI para generar proxies más adelante en esta sección.
Sin destino	Es un proxy de API sin backend de API (“sin destino”). Es similar a la creación de un proxy inverso para un servicio HTTP descrita antes, a excepción de que no especificarás una API existente cuando definas los detalles del proxy de API. Haz clic en Usar una especificación de OpenAPI para generar el proxy a partir de una especificación de OpenAPI válida. Si deseas obtener más información sobre esta opción, consulta Usa especificaciones de OpenAPI para generar proxies más adelante en esta sección.
Paquete de proxy de carga	Es un paquete de proxy de API existente (por ejemplo, uno de los proxies de API de muestra disponibles en GitHub). Consulta Importa un proxy de API desde un paquete de proxy de API.

En las siguientes secciones se analizan los detalles de cada tipo de proxy.

Crea un proxy inverso para un servicio HTTP

Apigee genera proxies inversos según la siguiente información:

• La URL del servicio de backend.
• La ruta de acceso del URI que identifica de forma única la API que mostrará el proxy de la API a las aplicaciones para consumidores.

La URL del servicio de backend, por lo general, representa una aplicación con el servicio habilitado que es propiedad de tu organización. También puede apuntar a una API disponible de forma pública. La API o el servicio pueden estar bajo tu control (por ejemplo, una aplicación interna de RR.HH. o una aplicación de rieles en Cloud) o pueden ser de terceros (por ejemplo, Twitter o Instagram).

Los siguientes Detalles del proxy están disponibles después de acceder al Asistente de Creación de proxy y seleccionar un tipo de proxy:

Campo	Descripción
Nombre	Es el nombre que se muestra para tu API. Especifica caracteres alfanuméricos, guiones (-) o guiones bajos (_).
Ruta base	Fragmento de URI que aparece después de la dirección http://[host] o https://[host] del tu proxy de API. Apigee usa el URI de la ruta base para hacer coincidir los mensajes de solicitud entrantes y enrutarlos al proxy de API adecuado. Nota: La ruta base del proxy de API se configura de forma predeterminada como el valor especificado para el campo Name, convertido en minúsculas. Luego de la ruta base se encuentran las URL de recursos adicionales. La estructura completa de URL que usan los clientes para llamar al proxy de API es la siguiente: https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH Nota: La ruta base debe ser única. No puedes implementar dos proxies de API con la misma ruta base. Si editas un proxy de API implementado y configuras la ruta base con el mismo valor que la ruta base de otro proxy de API, Apigee anulará automáticamente la implementación de este proxy cuando lo guardes. Antes de poder volver a implementar el proxy de API, debes editar la ruta base para que sea única. Use comodines en las rutas base Usa uno o más comodines /*/ en las rutas base del proxy de API con el fin de preparar a los proxies de API para el futuro. Por ejemplo, una ruta base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y a https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para admitir equipos nuevos. Ten en cuenta que no se admite /**/.
Descripción	Es la descripción de la API (opcional).
(API existente) de destino	Es la URL del servicio de backend que invoca este proxy de API.

Importa un proxy de API desde un paquete de proxy de API

Nota: Cuando importas un proxy de API desde un paquete de proxy de API, eres responsable de configurar la seguridad del paquete y agregar políticas en este. La IU no te solicita que agregues seguridad ni políticas cuando importas el paquete, como se describe en Agrega seguridad más adelante en esta sección.

A menudo, debes definir los proxies de API como una colección de archivos XML, junto con cualquier otro archivo de compatibilidad. Cuando defines tus proxies de API como un conjunto de archivos externos a Apigee, puedes mantenerlos en un sistema de control de fuente y, luego, importarlos a Apigee para probarlos e implementarlos.

Para importar proxies de API desde un paquete de proxy de API, sigue estos pasos:

1. Accede al asistente de Creación de proxy, como se describe en Crea un proxy de API mediante la IU antes en esta sección.
2. Haz clic en Subir paquete de proxy.

3. En la página Subir paquete de proxy del asistente de proxy, ingresa la siguiente información:

   Campo	Descripción
   Paquete ZIP	Es el archivo ZIP que contiene la configuración del proxy de API. Arrastra y suelta o haz clic para navegar hasta el archivo.
   Nombre	Es el nombre que se muestra para tu API. Se configura de forma predeterminada como el nombre del archivo ZIP sin la extensión.

4. Haz clic en Siguiente.

5. En la página Resumen, selecciona los entornos de implementación, si lo deseas, y haz clic en Crear e implementar.

   Aparecerá un mensaje de confirmación que confirma que se creó correctamente tu nuevo proxy de API.

6. Haz clic en Editar proxy para mostrar la página de detalles del proxy de API.

Crea proxies de API de gRPC

Además de los proxies de API de REST, Apigee admite proxies de API de gRPC solo con compatibilidad con la transferencia en este momento. Con la compatibilidad de traspaso, la carga útil de gRPC es opaca para Apigee y el tráfico se enruta desde el cliente de gRPC al servidor de destino de gRPC preconfigurado en la configuración de destino.

En este momento, los proxies de API de gRPC de Apigee tienen las siguientes características:

• Admite solicitudes de gRPC unarias.
• No se pueden usar políticas que afecten la carga útil.
• Se puede usar en productos de API que no están asociados con proxies de GraphQL o REST. Las cuotas específicas de los productos de API y otras opciones de configuración de operaciones se aplican a todos los proxies del producto.
• No son compatibles con Apigee Hybrid.
• Usa dos variables de flujo específicas de gRPC: request.grpc.rpc.name y request.grpc.service.name.
• Se puede supervisar con estas variables de Apigee Analytics específicas: x_apigee_grpc_rpc_name, x_apigee_grpc_service_name y x_apigee_grpc_status.
• Muestra los códigos de estado de gRPC.

También debes configurar el balanceador de cargas para que admita gRPC. Consulta Usa gRPC con tus aplicaciones y Usa los comandos de la CLI de gcloud a fin de crear enrutamiento para gRPC.

Para crear un proxy de API de gRPC, primero define un servidor de destino de gRPC (consulta Crea TargetServers) y, luego, especifica ese servidor de destino cuando crees el proxy nuevo.

Nota: La configuración del proxy de gRPC a través de la IU de Apigee solo es compatible con la IU de Apigee en la consola de Cloud, no con otras consolas de Apigee.

Usa comandos de la CLI de gcloud para crear enrutamiento para gRPC

En esta sección, se muestran comandos de ejemplo para crear enrutamiento de proxies de gRPC, con la CLI de gcloud. Las instrucciones incluyen la configuración de balanceadores de cargas, un servidor de destino y un MIG.

Esta sección no es una guía completa para crear el enrutamiento. Es posible que estos ejemplos no sean adecuados para todos los casos prácticos. Además, estas instrucciones suponen que estás familiarizado con el enrutamiento externo (MIG) y la configuración de gRPC del balanceador de cargas de Cloud.

Configure las variables de entorno

Estas variables de entorno se usan en los comandos de las subsecciones.

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Comandos de la CLI de gcloud de ejemplo para crear enrutamiento de proxies de gRPC con balanceadores de cargas nuevos

En esta sección, se muestran comandos de ejemplo para crear proxies de gRPC con la CLI de gcloud y un balanceador de cargas nuevo. Las instrucciones incluyen la configuración del balanceador de cargas, un servidor de destino y un MIG.

Crea la plantilla de instancias.

gcloud compute instance-templates create $MIG_NAME \
--project $PROJECT_ID \
--region $REGION \
--network $VPC_NAME \
--subnet $VPC_SUBNET \
--tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
--machine-type e2-medium --image-family debian-12 \
--image-project debian-cloud --boot-disk-size 20GB \
--no-address \
--metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

Crea el grupo de instancias administrado

gcloud compute instance-groups managed create $MIG_NAME \
--project $PROJECT_ID --base-instance-name apigee-mig \
--size 2 --template $MIG_NAME --region $REGION

Configura el ajuste de escala automático

gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
--project $PROJECT_ID --region $REGION --max-num-replicas 50 \
--target-cpu-utilization 0.75 --cool-down-period 90

Define un puerto con nombre

gcloud compute instance-groups managed set-named-ports $MIG_NAME \
--project $PROJECT_ID --region $REGION --named-ports https:443

Crea una clave y un certificado SSL administrados por Google para el balanceador de cargas

gcloud compute ssl-certificates create $CERTIFICATE_NAME \
--domains=$DOMAIN_HOSTNAME \
--project $PROJECT_ID \
--global

Valida que el certificado está aprovisionado

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \
--global \
--format="get(name,managed.status, managed.Status)"

Crea el balanceador de cargas global de Cloud (GCLB)

1. Crea una verificación de estado
   

   gcloud compute health-checks create https hc-apigee-envoy-443 \
   --project $PROJECT_ID --port 443 --global \
   --request-path /healthz/ingress

2. Crea el servicio de backend para http1
   

   gcloud compute backend-services create YOUR_BACKEND_1 \
   --project $PROJECT_ID \
   --protocol HTTPS \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

3. Crea el servicio de backend para http2
   

   gcloud compute backend-services create YOUR_BACKEND_2 \
   --project $PROJECT_ID \
   --protocol HTTP2 \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

4. Agrega MIG al servicio de backend. En este ejemplo, volvemos a usar el MIG, pero también puedes crear un nuevo par de MIG.
   

   gcloud compute backend-services add-backend YOUR_BACKEND_1 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

   gcloud compute backend-services add-backend YOUR_BACKEND_2 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

5. Crea un mapa de URL de balanceo de cargas. Primero, verifica si ya tienes un mapa de URL. Si lo tienes, asegúrate de modificar ese mapa según los requisitos a continuación, en lugar de reemplazarlo.
   

   Crea un archivo YAML o usa el archivo existente, en /tmp/apigee-map.yaml, con esta configuración. Ten en cuenta que el backend del mapa http1 de URL es el predeterminado.

   defaultService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1
   name: matcher1
   routeRules:
   - matchRules:
   - headerMatches:
   - headerName: Content-Type
   prefixMatch: application/grpc
   prefixMatch: /
   priority: 100
   routeAction:
   weightedBackendServices:
   - backendService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2
   weight: 100

   Valida el mapa de URL:

   gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID

   Crea el mapa de URL con el enrutamiento basado en encabezados:

   gcloud compute url-maps import apigee-http1-http2 \
   --source /tmp/apigee-map.yaml  \
   --global --project $PROJECT_ID

Crea un proxy HTTPS de destino de balanceo de cargas

gcloud compute target-https-proxies create apigee-envoy-https-proxy \
--project $PROJECT_ID --url-map apigee-envoy-proxy-map \
--ssl-certificates $CERTIFICATE_NAME

Reserva una IPV4 externa y crea reglas de firewall para el balanceador de cargas

gcloud compute addresses create lb-ipv4-vip-1 \
--project $PROJECT_ID \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global

  gcloud compute addresses describe lb-ipv4-vip-1 \
--project $PROJECT_ID --format="get(address)" --global

  gcloud compute forwarding-rules create apigee-envoy-https-lb-rule \
--project $PROJECT_ID --address lb-ipv4-vip-1 --global \
--target-https-proxy apigee-envoy-https-proxy --ports 443

Crear una regla de firewall

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \
--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

Comandos de la CLI de gcloud de ejemplo que crean enrutamiento de proxies de gRPC para balanceadores de cargas existentes

En esta sección, se muestran comandos de ejemplo para crear proxies de gRPC con la CLI de gcloud y un balanceador de cargas existente. Las instrucciones incluyen la configuración del balanceador de cargas, un servidor de destino y un MIG.

Crea otro servicio de backend para http2

# Create backend service for http2
    gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

Conecta el segundo servicio de backend al MIG

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

Enumera el mapa de URL para el GCLB de Apigee existente

gcloud compute url-maps list -project $PROJECT_ID

Selecciona el nombre correcto del mapa de URL que se usó para el balanceo de cargas de Apigee

gcloud compute url-maps export APIGEE_URL_MAP_NAME -project $PROJECT_ID

Crea un archivo YAML de mapa de URL de balanceo de cargas

Si ya tienes un mapa de URL existente, combina esta configuración. De lo contrario, crea un archivo YAML en /tmp/apigee-map.yaml con esta configuración.

defaultService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2
weight: 100

Aplica el YAML nuevo para el enrutamiento de gRPC

gcloud compute url-maps import APIGEE_URL_MAP_NAME\
--source /tmp/apigee-map.yaml  \
--global -project $PROJECT_ID

Agrega seguridad

En la página Políticas comunes del asistente de Creación de proxy, selecciona el tipo de autorización de seguridad que deseas agregar. En la siguiente tabla, se resumen las opciones disponibles:

Autorización de seguridad	Descripción
Clave de API	Agrega una verificación de clave de API simple al proxy de API que estás definiendo. En respuesta, la plataforma de la API agrega una política VerifyAPIKey nueva y una política AssignMessage al proxy de API. La política VerifyAPIKey valida las claves de API presentadas mediante la solicitud de apps. La política AssignMessage quita la clave de API, proporcionada en la llamada a la API como parámetro de consulta, de la solicitud reenviada al servidor de backend.
OAuth 2.0	Agrega una autenticación basada en OAuth 2.0 a tu proxy de API. Apigee agrega automáticamente las siguientes políticas a tu proxy de API: una para verificar un token de acceso y otra para quitarlo del mensaje antes de reenviarlo a tu servicio de backend. Para aprender a obtener un token de acceso, consulta OAuth.
Transferencia (sin autorización)	No se requiere autorización. Las solicitudes se pasan al backend sin ninguna verificación de seguridad en Apigee.

Agrega compatibilidad con CORS

El uso compartido de recursos entre dominios (CORS) es un mecanismo estándar que permite que un navegador web realice solicitudes directas a otro dominio. En el estándar de CORS, se define un conjunto de encabezados HTTP que los servidores y los navegadores web usan para implementar la comunicación entre dominios.

Puedes agregar compatibilidad con CORS mediante una de las siguientes opciones:

• Agrega la política de CORS a la solicitud de flujo previo de ProxyEndpoint
• Selecciona Agregar encabezados de CORS en la página Políticas comunes del asistente de creación de proxy.

Para obtener más información detallada sobre la compatibilidad con CORS, incluida la adición de la compatibilidad con la verificación previa de CORS a un proxy, consulta Agrega la compatibilidad con CORS a un proxy de API.

Agrega cuotas

Las cuotas protegen el servicio de backend del tráfico alto en Cuota. Consulta Cuotas (No está disponible si se selecciona la autorización de transferencia).

Usa especificaciones de OpenAPI para generar proxies

En esta sección, se analiza la opción de usar OpenAPI que está disponible para generar los siguientes tipos de proxies de API desde una especificación de OpenAPI: inverso o sin destino.

¿Qué es una especificación de OpenAPI?

"Open API Initiative (OAI) se enfoca en crear, desarrollar y promocionar un formato de descripción de API que no dependa de los proveedores y esté basado en la especificación de Swagger". Para obtener más información, consulta OpenAPI Initiative.

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 para las máquinas, pero también es fácil de leer y comprender. En la especificación se describen los elementos de la API como su ruta base, rutas y verbos, encabezados, parámetros de consulta, operaciones, tipos de contenido, descripciones de respuesta y mucho más. Además, una especificación de OpenAPI se suele usar para generar documentación de la API.

El siguiente fragmento de una especificación de OpenAPI describe el servicio de objetivo ficticio de Apigee, http://mocktarget.apigee.net. A fin de obtener más información, consulta la especificación de OpenAPI para la muestra de helloworld.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

A través del asistente de creación de proxy, puedes importar una especificación de OpenAPI y usarla para generar un proxy de API. Una vez que se genera el proxy, puedes usar la IU de Apigee para desarrollarlo aún más mediante el agregado de políticas, la implementación de código personalizado, y demás, del mismo modo que con cualquier proxy de Apigee.

Crea un proxy de API a partir de una especificación de OpenAPI

Crea tus proxies de API desde una especificación de OpenAPI. Con solo unos clics, tendrás un proxy de API con las rutas, los parámetros, los flujos condicionales y los extremos de destino generados automáticamente. Luego puedes agregar características como la seguridad de OAuth, el límite de frecuencia y el almacenamiento en caché.

En el asistente de creación de proxy, haz clic en Usa especificaciones de OpenAPI y sigue el asistente para crear un proxy inverso o uno sin destino desde una especificación de OpenAPI. Para obtener más detalles, consulta Crea un proxy de API desde una especificación de OpenAPI.

Crea una revisión nueva de un proxy de API

Crea una revisión nueva de un proxy de API, como se describe a continuación.

Para crear una revisión nueva de un proxy de API, sigue estos pasos:

1. Accede a la IU de Apigee.
2. En la barra de navegación, selecciona Desarrollar > Proxies de API.
3. Haz clic en el proxy de API en la lista que deseas copiar.

4. Haz clic en la pestaña Desarrollar:

5. Selecciona el botón Guardar y selecciona Guardar como revisión nueva.

Crea una copia de seguridad de un proxy de API

Puedes crear una copia de seguridad de un proxy de API existente como un conjunto de archivos XML en un paquete de proxy de API. Una vez exportado a un paquete, puedes importar el proxy de API a un proxy nuevo, como se describe en Importa un proxy de API desde un paquete de proxy de API antes en esta sección. Para obtener más información, consulta Descarga proxies de API.

Crea un proxy de API mediante la API

Para crear un proxy de API con la API, consulta Crea un proxy de API.