Tutoriel Lightweight Gateway

Essayez la Lightweight Gateway en utilisant la définition de l'API fournie pour créer un produit et le publier, puis testez l'API.

Avertissement : L'aperçu de Lightweight Gateway ne prend actuellement en charge que HTTP. N'utilisez pas cet environnement pour des charges de travail de production.

Télécharger le kit d'outils CLI et se connecter

Ce tutoriel peut être réalisé à l'aide de l'interface utilisateur ou de la boîte à outils CLI API Connect . Les instructions suivantes concernent la boîte à outils.

  1. Téléchargez la boîte à outils et configurez-la comme expliqué dans Téléchargement de la boîte à outils.

  2. Connectez-vous à API Connect comme expliqué dans Logging in the toolkit.

Créer un catalogue à utiliser avec ce tutoriel

Lorsque vous créez un catalogue, le Lightweight Gateway lui est automatiquement associé.

Créez un catalogue en utilisant le fichier de données catalog.yaml :

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

Fichier de données : Créez un fichier YAML appelé catalog.yaml avec le contenu suivant.

name: previewcatalog

Exemple :

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

Activez les services Lightweight Gateway dans le catalogue. Pour plus d'informations, voir ... /com.ibm.apic.apionprem.doc/create_env.html.

Ajouter un profil client TLS à l'organisation proPreviewcOrg.yamlvider

Créez un profil de client TLS et ajoutez-le à votre organisation de fournisseurs. Le profil client TLS est utilisé pour l'authentification lorsque l'API est invoquée.

  1. Créez un profil de client TLS à l'aide du fichier tlsclientprofile.yaml et enregistrez le fichier TLS_PROFILE_URL dans une variable d'environnement :
    TLS_PROFILE_URL=$(./apic -s <platform_endpoint_url> tls-client-profiles:create -o <org_name> tlsclientprofile.yaml --format json | jq -r '.url')

    Fichier de données : Créez un fichier YAML appelé tlsclientprofile.yaml avec le contenu suivant :

    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

    Exemple :

     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. Ajoutez le profil client TLS au catalogue en utilisant le fichier configuredtlsclientprofile.yaml :
    ./apic -s <platform_endpoint_url> configured-tls-client-profiles:create -o <org_name> -c <catalog_name> --scope catalog configuredtlsclientprofile.yaml

    Fichier de données : Générer un fichier YAML appelé configuredtlsclientprofile.yaml :

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

    Exemple :

    • Commande :
      ./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
    • Réponse :
      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

Ajouter un produit au catalogue

La mise à disposition d'un produit déploie une copie de celui-ci dans le catalogue cible sans que le produit ne soit visible pour les développeurs.

Note : Pour cet aperçu, vous ne pouvez mettre en scène qu'un produit particulier dans un seul catalogue.

Mettez en scène le produit en utilisant le fichier produit lwgw-product-demo.yaml et le fichier API demo , et enregistrez le fichier PRODUCT_URL dans une variable d'environnement :

PRODUCT_URL=$(./apic -s  products:publish -c <catalog_name> -o <org_name> --stage <path_to_product_yaml> --format json | jq -r '.url')
Fichier de données : Créez un fichier YAML appelé demo.yaml avec le contenu suivant :
Note : Ce fichier est la définition OpenAPI qui décrit l'API que vous publiez et testez à l'aide de l'application 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
Remarque : le champ targetUrl utilisé précédemment dans l'exemple de code demo.yaml est toujours pris en charge dans le cadre de cet aperçu technologique, mais il ne le sera plus lors de la publication générale. L'exemple de code utilise maintenant le champ endpoint
Fichier de données : Créez un fichier YAML appelé lwgw-product-demo.yaml avec le contenu suivant :
Remarque : ce fichier est le fichier de définition du produit, qui définit le produit API regroupant une ou plusieurs API (comme celui qui figure à l'adresse 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
Exemple :
Note : Votre API et votre produit sont maintenant définis. La commande suivante permet d'ajouter le produit au catalogue. La mise en scène prépare le produit à la publication, mais ne le rend pas encore visible pour les développeurs.
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')

Publier le produit

La publication d'un produit déploie une version statique du produit et de l'API dans le catalogue et la rend visible aux autres développeurs qui travaillent dans ce catalogue. Après avoir publié le produit, vous pouvez le retirer de la circulation, puis le réintroduire dans le catalogue pour l'utiliser dans la suite de ce tutoriel.

Note : Pour cet aperçu, vous ne pouvez publier qu'un produit particulier dans un seul catalogue.
Remarque : la variable PRODUCT_URL que vous avez définie lors de l'étape de mise à disposition n'est pas utilisée lors de l'étape de publication. Vous utiliserez cette variable ultérieurement lorsque vous créerez un abonnement pour une application client.

Publier le produit en utilisant le fichier updatestate.yaml :

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

Fichier de données : Créez un fichier YAML appelé updatestate.yaml avec le contenu suivant :

state: published

Exemple :

./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

Étapes facultatives pour prendre sa retraite et remettre en scène l'API :

  • Retirez le produit en utilisant le fichier retire.yaml :
    /apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog retire.yaml

    Fichier de données : Créez un fichier YAML appelé retire.yaml avec le contenu suivant :

    state: retired

    Exemple :

    ./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
  • Mettez en scène le produit retiré en utilisant le fichier staged.yaml :
    ./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog staged.yaml

    Fichier de données : Créez un fichier YAML appelé staged.yaml avec le contenu suivant :

    state: staged

    Exemple :

    ./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

Création d'un utilisateur

Créer un utilisateur qui consomme le produit API. Lorsque vous créez une application client qui appelle l'API dans une étape ultérieure, elle nécessite une organisation de consommateurs avec au moins un utilisateur.

  1. Liste des registres d'utilisateurs disponibles pour votre organisme fournisseur :
    ./apic -s <platform_endpoint_url> user-registries:list -o <org_name>

    Exemple :

    • Commande :
      ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com user-registries:list -o lwgw-demo
    • Réponse :
      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. Ajoutez un utilisateur au registre previewcatalog-catalog en utilisant le fichier user.yaml et enregistrez le fichier OWNER_URL dans une variable d'environnement :
    OWNER_URL=$(./apic -s <platform_endpoint_url>  users:create -o <org_name> --user-registry <user_registry_name> user.yaml  --format json | jq '.url')

    Fichier de données : Créez un fichier YAML appelé user.yaml avec le contenu suivant :

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

    Exemple :

    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. Répertoriez les utilisateurs dans le registre pour vérifier que votre nouvel utilisateur a bien été ajouté :
    ./apic -s <platform_endpoint_url> users:list -o <org_name> --user-registry <user_registry_name>

    Exemple :

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

    Notez l'adresse URL de votre nouvel utilisateur ; vous en aurez besoin lorsque vous ajouterez une organisation de consommateurs à l'étape suivante.

Créer une organisation de consommateurs avec le nouvel utilisateur

L'organisation de consommateurs contient la liste des développeurs d'applications qui peuvent utiliser vos API. Lorsque vous créez une organisation de consommateurs, vous ajoutez un registre d'utilisateurs et les personnes figurant dans ce registre deviennent membres de la nouvelle organisation de consommateurs.

Utilisez le fichier de données fourni pour créer une organisation de consommateurs en utilisant le registre previewcatalog-catalog , qui inclut votre nouvel utilisateur John Preview.

Fichier de données : Générer un fichier YAML appelé previewCorg.yaml :

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

Créez une organisation de consommateurs en utilisant le fichier previewCorg.yaml :

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

Exemple :

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

Créer une application client et l'abonner à l'API

Créez une application et abonnez-la à une API. Les informations d'identification de l'application sont vérifiées lorsque vous appelez l'API. Complétez l'étape précédente pour créer l'organisation de consommateurs avant de pouvoir créer une application.

Pour ce tutoriel, vous n'aurez pas besoin de mettre en place un portail pour développeurs et de créer une application complète pour appeler l'API. Au lieu de cela, vous pouvez créer une application client simple et appeler l'API directement à partir du catalogue.

  1. Créez une application client en utilisant le fichier app.yaml :
    ./apic -s <platform_endpoint_url> apps:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> app.yaml

    Fichier de données : Créez un fichier YAML appelé app.yaml avec le contenu suivant :

    name: apppreview

    Exemple :

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com apps:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg app.yaml
  2. Créez un abonnement en utilisant le fichier subscription.yaml (vous devez créer l'application avant de pouvoir créer un abonnement) :
    ./apic -s <platform_endpoint_url> subscriptions:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> --app <app_name>
    Générer le fichier de données : subscription.yaml
    Note : Cette commande identifie le produit échelonné auquel l'application client est abonnée.
    echo "{product_url: $PRODUCT_URL, plan: default-plan}" > subscription.yaml

    Exemple :

    ./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

Vérifiez que vos commandes ont fonctionné

Vérifiez les résultats de vos commandes sur la passerelle. Cela vous indique si toutes les commandes ont été appliquées ou si certaines sont encore en attente.

./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>

Exemple :

 ./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

Tester l'API avec le Lightweight Gateway

Utilisez curl pour effectuer quelques appels API rapides et voir comment se comporte Lightweight Gateway.

Copiez et exécutez chaque commande :
Note : Le endpoint doit inclure le nom de votre catalogue, le nom du produit et le nom de l'organisme fournisseur dans le format suivant : http://{product}-{catalog}-{org}.{gateway_name}.rosa.apic-v-lw01.lugt.p3.openshiftapps.com/{version}/{server_url}/{path}
  • Mauvaise demande - La demande n'est pas analysée
    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

    Cette demande est une mauvaise demande car la terminaison ] est absente du tableau et la demande ne peut pas être analysée.

  • Mauvaise demande - La demande n'est pas validée
    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

    Il s'agit d'une mauvaise requête car, bien que le tableau soit formaté correctement, le schéma de la requête stipule que les données affichées doivent être un objet JSON (et non un tableau).

  • Réponse valide
    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

    Il s'agit d'une réponse valide car l'en-tête Format est renvoyé sous la forme de la chaîne simple par httpbin.org, ce qui est conforme à l'exigence du schéma de réponse selon laquelle /headers/Format doit respecter les contraintes Enum de simple ou complex.