Guía de aprendizaje de Lightweight Gateway

Prueba el Lightweight Gateway utilizando la definición de API proporcionada para crear un producto y publicarlo, y luego prueba la API.

Advertencia: La vista previa de Lightweight Gateway sólo admite actualmente HTTP. No utilice este entorno para cargas de trabajo de producción.

Descargue el conjunto de herramientas CLI e inicie sesión

Este tutorial puede realizarse utilizando la interfaz de usuario o API Connect CLI toolkit. Las siguientes instrucciones son para el kit de herramientas.

  1. Descarga el kit de herramientas y configúralo como se explica en Descargar el kit de herramientas.

  2. Inicia sesión en API Connect como se explica en Inicio de sesión en el kit de herramientas.

Crear un catálogo para utilizar con este tutorial

Al crear un catálogo, se le asocia automáticamente el Lightweight Gateway.

Cree un catálogo utilizando el archivo de datos catalog.yaml :

./apic -s <platform_endpoint_url> catalogs:create -o <org_name> catalog.yaml

Fichero de datos: Cree un archivo YAML llamado catalog.yaml con el siguiente contenido.

name: previewcatalog

Ejemplo:

  • Mandato:
    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com catalogs:create -o lwgw-demo catalog.yaml
  • Respuesta:
    previewcatalog https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/catalogs/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e80bfea1-bf1d-4af1-9d60-4fa1c16e836f

Habilite los servicios Lightweight Gateway en el catálogo. Para más información, consulte .. /com.ibm.apic.apionprem.doc/create_env.html.

Añadir un perfil de cliente TLS a la organización proPreviewcOrg.yamlvider

Cree un perfil de cliente TLS y añádalo a su organización proveedora. El perfil de cliente TLS se utiliza para la autenticación cuando se invoca la API.

  1. Cree un perfil de cliente TLS utilizando el archivo tlsclientprofile.yaml , y guarde el TLS_PROFILE_URL en una variable de entorno:
    TLS_PROFILE_URL=$(./apic -s <platform_endpoint_url> tls-client-profiles:create -o <org_name> tlsclientprofile.yaml --format json | jq -r '.url')

    Fichero de datos: Crea un archivo YAML llamado tlsclientprofile.yaml con el siguiente contenido:

    ciphers:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_AES_128_GCM_SHA256
- ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- ECDHE_RSA_WITH_AES_256_GCM_SHA384
- ECDHE_RSA_WITH_AES_256_CBC_SHA384
- ECDHE_RSA_WITH_AES_128_GCM_SHA256
- ECDHE_RSA_WITH_AES_128_CBC_SHA256
- ECDHE_RSA_WITH_AES_256_CBC_SHA
- ECDHE_RSA_WITH_AES_128_CBC_SHA
- DHE_RSA_WITH_AES_256_GCM_SHA384
- DHE_RSA_WITH_AES_256_CBC_SHA256
- DHE_RSA_WITH_AES_128_GCM_SHA256
- DHE_RSA_WITH_AES_128_CBC_SHA256
- DHE_RSA_WITH_AES_256_CBC_SHA
- DHE_RSA_WITH_AES_128_CBC_SHA
title: httpd
name: httpd
version: 1.0.0
summary: ''
insecure_server_connections: false
server_name_indication: true
protocols:
- tls_v1.2
- tls_v1.3

    Ejemplo:

     TLS_PROFILE_URL=$(./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com tls-client-profiles:create -o lwgw-demo tlsclientprofile.yaml ---format json | jq -r '.url')
  2. Añada el perfil de cliente TLS al catálogo utilizando el archivo configuredtlsclientprofile.yaml :
    ./apic -s <platform_endpoint_url> configured-tls-client-profiles:create -o <org_name> -c <catalog_name> --scope catalog configuredtlsclientprofile.yaml

    Fichero de datos: Genera un archivo YAML llamado configuredtlsclientprofile.yaml:

    echo "{tls_client_profile_url: $TLS_PROFILE_URL}" > configuredtlsclientprofile.yaml

    Ejemplo:

    • Mandato:
      ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com configured-tls-client-profiles:create -o lwgw-demo -c previewcatalog --scope catalog configuredtlsclientprofile.yaml
    • Respuesta:
      httpd:1.0.0   https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/catalogs/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e80bfea1-bf1d-4af1-9d60-4fa1c16e836f/configured-tls-client-profiles/c1b1d8a8-9843-40a8-9f5e-a65f5ebcaf1e

Añadir un producto al catálogo

La puesta en escena de un producto despliega una copia del mismo en el catálogo de destino sin que el producto sea visible para ningún desarrollador.

Nota: Para esta vista previa, sólo puede poner en escena un producto concreto en un catálogo.

Ponga en escena el producto utilizando el archivo de producto lwgw-product-demo.yaml y el archivo API demo , y guarde PRODUCT_URL en una variable de entorno:

PRODUCT_URL=$(./apic -s  products:publish -c <catalog_name> -o <org_name> --stage <path_to_product_yaml> --format json | jq -r '.url')
Fichero de datos: Crea un archivo YAML llamado demo.yaml con el siguiente contenido:
Nota: Este archivo es la definición de OpenAPI que describe la API que publica y prueba mediante el uso de Lightweight Gateway.
openapi: 3.0.2
servers:
- url: "/demo"
info:
  title: Demo
  description: Demonstrate the capabilities of the lightweight gateway
  version: 1.0.0
  x-ibm-name: demo
  x-ibm-summary: Demo API
x-ibm-configuration:
  gateway: lightweight-gateway
  compatibility:
    suppress-limitation-errors: true
  assembly:
    catch: []
    execute:
      - parse:
          documentType: json
          input: request
      - validate:
          input: request
          request:
            schema:
              validateSchema: true
      - set:
          variable:
            name: arg
            value: '$header("request", "x-arg")'
      - invoke:
          output: response
          endpoint:
            http:
              target:
                url: https://httpbin.org/anything
                tlsClientProfile: httpd:1.0.0
                timeout: 60
      - parse:
          documentType: json
          input: response
      - validate:
          input: response
          request:
            schema:
              validateSchema: true
      - set:
          messageHeader:
            headerName: my-header-name
            messageName: response
            value: '123'
    finally: []
tags:
- name: demo
  description: good for demo purposes
paths:
  "/test":
    post:
      responses:
        default:
          description: ensure response meets schema expectations
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MyResponse"
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Object"
components:
  schemas:
    Object:
      type: object
    MyResponse:
      type: object
      properties:
        headers:
          type: object
          properties:
            Format:
              type: array
              items:
                type: string
                enum:
                - simple
                - complex
        json:
          type: object
          properties:
            pet-name:
              type: string
            pet-type:
              type: string
              enum:
              - dog
              - bird
Nota: El campo targetUrl utilizado anteriormente en el ejemplo de código demo.yaml sigue siendo compatible con esta versión preliminar de la tecnología, pero no lo será con la versión general. El ejemplo de código utiliza ahora el campo endpoint.
Archivo de datos: Crea un archivo YAML llamado lwgw-product-demo.yaml con el siguiente contenido:
Nota: Este archivo es el archivo de definición del producto, que define el producto API que agrupa una o varias API (como el que aparece en demo.yaml ).
info:
  version: 1.0.0
  title: lwgw-product-demo
  name: lwgw-product-demo
gateways:
- lightweight-gateway
plans:
  default-plan:
    title: Default Plan
    description: Default Plan
    rateLimitMap:
      plan-limit: default
components:
  rateLimits:
    default:
    - max: 100
      intervalLen: 1
      intervalUnit: hour
apis:
  demo:
    $ref: demo.yaml
visibility:
  view:
    type: public
    orgs: []
    tags: []
    enabled: true
  subscribe:
    type: authenticated
    orgs: []
    tags: []
    enabled: true
product: 1.0.0
Ejemplo:
Nota: Ahora, su API y el producto está definido. El siguiente comando es para poner el producto en el catálogo. La puesta en escena prepara el producto para su publicación, pero aún no lo hace visible para los desarrolladores.
PRODUCT_URL=$(./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com products:publish -c previewcatalog -o lwgw-demo --stage  lwgw-product-demo.yaml --format json | jq -r '.url')

Publicar el producto

La publicación de un producto despliega una versión estática del producto y la API en el catálogo, y lo hace visible para otros desarrolladores que trabajen en ese catálogo. Después de publicar el producto, puede retirarlo de uso, y luego ponerlo en el catálogo de nuevo para su uso en el resto de este tutorial.

Nota: Para esta vista previa, sólo puede publicar un producto concreto en un catálogo.
Nota: La variable PRODUCT_URL establecida durante el paso de preparación no se utiliza en el paso de publicación. Esta variable se utiliza más adelante cuando se crea una suscripción para una aplicación cliente.

Publique el producto utilizando el archivo updatestate.yaml :

./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog updatestate.yaml

Fichero de datos: Crea un archivo YAML llamado updatestate.yaml con el siguiente contenido:

state: published

Ejemplo:

./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog updatestate.yaml

Pasos opcionales para retirar y volver a poner en escena la API:

  • Retire el producto utilizando el archivo retire.yaml :
    /apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog retire.yaml

    Fichero de datos: Crea un archivo YAML llamado retire.yaml con el siguiente contenido:

    state: retired

    Ejemplo:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog retire.yaml
  • Ponga en escena el producto retirado utilizando el archivo staged.yaml :
    ./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog staged.yaml

    Fichero de datos: Crea un archivo YAML llamado staged.yaml con el siguiente contenido:

    state: staged

    Ejemplo:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com products:update -c previewcatalog -o lwgw-demo lwgw-product-demo:1.0.0 --scope catalog staged.yaml

Creación de un usuario

Crear un usuario que consuma el producto API. Cuando cree una aplicación cliente que llame a la API en un paso posterior, necesitará una organización de consumidores con al menos un usuario.

  1. Enumere los registros de usuarios disponibles para su organización proveedora:
    ./apic -s <platform_endpoint_url> user-registries:list -o <org_name>

    Ejemplo:

    • Mandato:
      ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com user-registries:list -o lwgw-demo
    • Respuesta:
      previewcatalog-catalog   https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/e24e1568-0f83-484d-8d1e-86376e1b26d2
sandbox-catalog          https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/243d3bc3-9afd-4d31-b698-893fe3aa0b5f
ibm-verify-test          https://platform-api.us-east-a.apiconnect.automation.ibm.com/api/user-registries/1273ce81-ef2c-4d01-96c4-5f33c1af119e/ab3e089f-20f9-4b85-b74a-448eb5ae284c
  2. Añade un usuario al registro previewcatalog-catalog utilizando el archivo user.yaml , y guarda el OWNER_URL en una variable de entorno:
    OWNER_URL=$(./apic -s <platform_endpoint_url>  users:create -o <org_name> --user-registry <user_registry_name> user.yaml  --format json | jq '.url')

    Fichero de datos: Crea un archivo YAML llamado user.yaml con el siguiente contenido:

    username: johnpreview
email: john.preview@us.ibm.com
first_name: John
last_name: Preview
password: usermustchangePassw0rd!

    Ejemplo:

    OWNER_URL=$(./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com users:create -o lwgw-demo --user-registry previewcatalog-catalog user.yaml  --format json | jq '.url')
  3. Listar los usuarios en el registro para verificar que su nuevo usuario fue añadido:
    ./apic -s <platform_endpoint_url> users:list -o <org_name> --user-registry <user_registry_name>

    Ejemplo:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com users:list -o lwgw-demo --user-registry previewcatalog-catalog

    Anote el URL para su nuevo usuario; lo necesitará cuando añada cuando cree una organización de consumidores en el siguiente paso.

Crear una organización de consumidores con el nuevo usuario

La organización de consumidores contiene la lista de desarrolladores de aplicaciones que pueden utilizar sus API. Cuando cree una organización de consumidores, añada un registro de usuarios y las personas que figuren en ese registro se convertirán en miembros de la nueva organización de consumidores.

Utilice el archivo de datos proporcionado para crear una organización de consumidores utilizando el registro previewcatalog-catalog , que incluye su nuevo usuario John Preview.

Fichero de datos: Genera un archivo YAML llamado previewCorg.yaml:

echo "{name: previewCorg, owner_url: $OWNER_URL, title:previewCorg}" > previewCorg.yaml

Cree una organización de consumidores utilizando el archivo previewCorg.yaml :

./apic -s <platform_endpoint_url> consumer-orgs:create -o <org_name> -c <catalog_name> previewCorg.yaml

Ejemplo:

./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com consumer-orgs:create -o lwgw-demo -c previewcatalog previewCorg.yaml

Crear una aplicación cliente y suscribirla a la API

Crear una aplicación y suscribirla a una API. Las credenciales de la aplicación se verifican cuando se llama a la API. Complete el paso anterior para crear la organización de consumidores antes de poder crear una aplicación.

Para este tutorial, no necesitará configurar un Portal del Desarrollador y crear una aplicación completa para llamar a la API. En su lugar, puede crear una sencilla aplicación cliente y llamar a la API directamente desde el catálogo.

  1. Cree una aplicación cliente utilizando el archivo app.yaml :
    ./apic -s <platform_endpoint_url> apps:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> app.yaml

    Fichero de datos: Crea un archivo YAML llamado app.yaml con el siguiente contenido:

    name: apppreview

    Ejemplo:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com apps:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg app.yaml
  2. Cree una suscripción utilizando el archivo subscription.yaml (debe crear la aplicación antes de poder crear una suscripción):
    ./apic -s <platform_endpoint_url> subscriptions:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> --app <app_name>
    Generar el fichero de datos: subscription.yaml
    Nota: Esta recomendación identifica el producto por etapas al que se suscribe la aplicación cliente.
    echo "{product_url: $PRODUCT_URL, plan: default-plan}" > subscription.yaml

    Ejemplo:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com subscriptions:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg --app apppreview subscription.yaml

Comprueba que tus comandos han funcionado

Comprueba los resultados de tus comandos en la pasarela. Esto le indica si se han aplicado todos los comandos o si aún quedan algunos pendientes.

./apic -s <platform_endpoint_url> configured-gateway-services:get -o <org_name> -c <catlog_name> --scope catalog --fields "add(gateway_processing_status,events)" <gateway_name>

Ejemplo:

 ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com configured-gateway-services:get -o lwgw-demo -c previewcatalog --scope catalog --fields "add(gateway_processing_status,events)" lightweight-gateway

Prueba la API con el Lightweight Gateway

Utiliza curl para ejecutar algunas llamadas rápidas a la API y ver cómo se comporta Lightweight Gateway.

Copie y ejecute cada comando:
Nota: El endpoint debe incluir el nombre de su catálogo, el nombre del producto y el nombre de la organización proveedora en el siguiente formato: http://{product}-{catalog}-{org}.{gateway_name}.rosa.apic-v-lw01.lugt.p3.openshiftapps.com/{version}/{server_url}/{path}
  • Solicitud incorrecta - No analiza la solicitud
    curl -v --header "Content-Type: application/json" --request POST --data '["foo", "bar"' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/demo/test

    Esta petición es incorrecta porque falta la terminación ] en el array y la petición no puede ser analizada.

  • Bad Request - No valida la solicitud
    curl -v --header "Content-Type: application/json" --request POST --data '["foo", "bar"]' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/demo/test

    Se trata de una solicitud incorrecta porque, aunque el array está formateado correctamente, el esquema de la solicitud dicta que los datos enviados deben ser un objeto JSON (no un array).

  • Respuesta válida
    curl -v --header "Content-Type: application/json" --header "Format: simple" --request POST --data '{}' http://lwgw-product-demo-previewcatalog-lwgw-demo.apic-gwlw-038.apps.apic-s-u01.nnna.p1.openshiftapps.com/1.0.0/demo/test

    Se trata de una respuesta válida porque httpbin.org devuelve la cabecera Format como la cadena simple, que cumple el requisito del esquema de respuesta de que /headers/Format debe cumplir las restricciones Enum de simple o complex.