Lightweight Gateway Lernprogramm

Probieren Sie die Lightweight Gateway aus, indem Sie die bereitgestellte API-Definition verwenden, um ein Produkt zu erstellen und zu veröffentlichen, und testen Sie dann die API.

Warnung: Die Vorschau von Lightweight Gateway unterstützt derzeit nur HTTP. Verwenden Sie diese Umgebung nicht für Produktionsworkloads.

Laden Sie das CLI-Toolkit herunter und melden Sie sich an

Dieses Tutorial kann entweder mit dem UI- oder dem API Connect CLI-Toolkit durchgeführt werden. Die folgenden Anweisungen beziehen sich auf das Toolkit.

  1. Laden Sie das Toolkit herunter und richten Sie es wie in Herunterladen des Toolkits beschrieben ein.

  2. Melden Sie sich bei API Connect an, wie in Anmeldung beim Toolkit beschrieben.

Erstellen Sie einen Katalog zur Verwendung mit diesem Tutorial

Wenn Sie einen Katalog erstellen, wird das Lightweight Gateway automatisch mit ihm verbunden.

Erstellen Sie einen Katalog mit Hilfe der Datei catalog.yaml :

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

Datendatei: Erstellen Sie eine YAML-Datei namens catalog.yaml mit folgendem Inhalt.

name: previewcatalog

Beispiel:

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

Aktivieren Sie die Dienste von Lightweight Gateway im Katalog. Weitere Informationen finden Sie unter ... /com.ibm.apic.apionprem.doc/create_env.html.

Hinzufügen eines TLS-Client-Profils zur Organisation proPreviewcOrg.yamlvider

Erstellen Sie ein TLS-Client-Profil und fügen Sie es zu Ihrer Anbieterorganisation hinzu. Das TLS-Clientprofil wird für die Authentifizierung beim Aufruf der API verwendet.

  1. Erstellen Sie ein TLS-Client-Profil mit Hilfe der Datei tlsclientprofile.yaml und speichern Sie TLS_PROFILE_URL in einer Umgebungsvariablen:
    TLS_PROFILE_URL=$(./apic -s <platform_endpoint_url> tls-client-profiles:create -o <org_name> tlsclientprofile.yaml --format json | jq -r '.url')

    Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen tlsclientprofile.yaml und folgendem Inhalt:

    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

    Beispiel:

     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. Fügen Sie das TLS-Client-Profil mit Hilfe der Datei configuredtlsclientprofile.yaml zum Katalog hinzu:
    ./apic -s <platform_endpoint_url> configured-tls-client-profiles:create -o <org_name> -c <catalog_name> --scope catalog configuredtlsclientprofile.yaml

    Daten-Datei: Erzeugen Sie eine YAML-Datei mit dem Namen configuredtlsclientprofile.yaml:

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

    Beispiel:

    • Befehl:
      ./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
    • Antwort:
      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

Ein Produkt in den Katalog aufnehmen

Beim Staging eines Produkts wird eine Kopie des Produkts im Zielkatalog bereitgestellt, ohne dass das Produkt für Entwickler sichtbar ist.

Hinweis: Bei dieser Vorschau können Sie nur ein bestimmtes Produkt für einen Katalog bereitstellen.

Führen Sie das Produkt mithilfe der Produktdatei lwgw-product-demo.yaml und der API-Datei demo aus, und speichern Sie PRODUCT_URL in einer Umgebungsvariablen:

PRODUCT_URL=$(./apic -s  products:publish -c <catalog_name> -o <org_name> --stage <path_to_product_yaml> --format json | jq -r '.url')
Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen demo.yaml und folgendem Inhalt:
Hinweis: Bei dieser Datei handelt es sich um die OpenAPI Definition, die die API beschreibt, die Sie mit Hilfe der Lightweight Gateway veröffentlichen und testen.
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
Hinweis: Das Feld targetUrl , das zuvor im Codebeispiel demo.yaml verwendet wurde, wird für diese Technologievorschau noch unterstützt, wird aber in der allgemeinen Version nicht mehr unterstützt. Das Codebeispiel verwendet jetzt das Feld endpoint.
Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen lwgw-product-demo.yaml und folgendem Inhalt:
Hinweis: Bei dieser Datei handelt es sich um die Produktdefinitionsdatei, die das API-Produkt definiert, das eine oder mehrere APIs bündelt (wie die Datei in 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
Beispiel:
Hinweis: Jetzt sind Ihre API und Ihr Produkt definiert. Mit dem folgenden Befehl wird das Produkt in den Katalog aufgenommen. Das Staging bereitet das Produkt für die Veröffentlichung vor, macht es aber noch nicht für die Entwickler sichtbar.
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')

Produkt veröffentichen

Durch die Veröffentlichung eines Produkts wird eine statische Version des Produkts und der API im Katalog bereitgestellt und für andere Entwickler, die in diesem Katalog arbeiten, sichtbar gemacht. Nachdem Sie das Produkt veröffentlicht haben, können Sie es aus dem Verkehr ziehen und wieder in den Katalog aufnehmen, um es im weiteren Verlauf dieses Tutorials zu verwenden.

Hinweis: Bei dieser Vorschau können Sie nur ein bestimmtes Produkt in einem Katalog veröffentlichen.
Hinweis: Die Variable PRODUCT_URL , die Sie während des Bereitstellungsschritts festgelegt haben, wird im Veröffentlichungsschritt nicht verwendet. Sie verwenden diese Variable später, wenn Sie ein Abonnement für eine Client-Anwendung erstellen.

Veröffentlichen Sie das Produkt mit Hilfe der Datei updatestate.yaml :

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

Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen updatestate.yaml und folgendem Inhalt:

state: published

Beispiel:

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

Optionale Schritte zum Zurückziehen und erneuten Bereitstellen der API:

  • Ziehen Sie das Produkt mit Hilfe der Datei retire.yaml zurück:
    /apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog retire.yaml

    Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen retire.yaml und folgendem Inhalt:

    state: retired

    Beispiel:

    ./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
  • Stellen Sie das ausgemusterte Produkt mit Hilfe der Datei staged.yaml ein:
    ./apic -s <platform_endpoint_url> products:update -c <catalog_name> -o <org_name> <product_name>:<product_version> --scope catalog staged.yaml

    Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen staged.yaml und folgendem Inhalt:

    state: staged

    Beispiel:

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

Benutzer erstellen

Erstellen Sie einen Benutzer, der das API-Produkt konsumiert. Wenn Sie eine Client-Anwendung erstellen, die die API in einem späteren Schritt aufruft, benötigt sie eine Verbraucherorganisation mit mindestens einem Benutzer.

  1. Listen Sie die verfügbaren Benutzerregister für Ihre Anbieterorganisation auf:
    ./apic -s <platform_endpoint_url> user-registries:list -o <org_name>

    Beispiel:

    • Befehl:
      ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com user-registries:list -o lwgw-demo
    • Antwort:
      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. Fügen Sie der Registrierung previewcatalog-catalog einen Benutzer hinzu, indem Sie die Datei user.yaml verwenden, und speichern Sie die Datei OWNER_URL in einer Umgebungsvariablen:
    OWNER_URL=$(./apic -s <platform_endpoint_url>  users:create -o <org_name> --user-registry <user_registry_name> user.yaml  --format json | jq '.url')

    Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen user.yaml und folgendem Inhalt:

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

    Beispiel:

    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. Listen Sie die Benutzer in der Registrierung auf, um zu überprüfen, ob Ihr neuer Benutzer hinzugefügt wurde:
    ./apic -s <platform_endpoint_url> users:list -o <org_name> --user-registry <user_registry_name>

    Beispiel:

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

    Notieren Sie sich die E-Mail-Adresse URL für Ihren neuen Benutzer. Sie benötigen sie, wenn Sie im nächsten Schritt eine Verbraucherorganisation erstellen.

Erstellen Sie eine Verbraucherorganisation mit dem neuen Benutzer

Die Verbraucherorganisation enthält die Liste der Anwendungsentwickler, die Ihre APIs nutzen können. Wenn Sie eine Verbraucherorganisation erstellen, fügen Sie eine Benutzerregistrierung hinzu, und die Personen, die in dieser Registrierung aufgeführt sind, werden Mitglieder der neuen Verbraucherorganisation.

Verwenden Sie die mitgelieferte Datendatei, um eine Verbraucherorganisation zu erstellen, indem Sie die previewcatalog-catalog -Registrierung verwenden, die Ihren neuen Benutzer John Preview enthält.

Daten-Datei: Erzeugen Sie eine YAML-Datei mit dem Namen previewCorg.yaml:

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

Erstellen Sie eine Verbraucherorganisation mit Hilfe der Datei previewCorg.yaml :

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

Beispiel:

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

Erstellen Sie eine Client-Anwendung und abonnieren Sie sie bei der API

Erstellen Sie eine Anwendung und abonnieren Sie sie bei einer API. Die Anmeldedaten der App werden beim Aufruf der API überprüft. Schließen Sie den vorherigen Schritt ab, um die Verbraucherorganisation zu erstellen, bevor Sie eine App erstellen können.

Für diesen Lehrgang müssen Sie kein Entwicklerportal einrichten und keine vollständige Anwendung erstellen, um die API aufzurufen. Stattdessen können Sie eine einfache Client-Anwendung erstellen und die API direkt über den Katalog aufrufen.

  1. Erstellen Sie eine Client-Anwendung unter Verwendung der Datei app.yaml :
    ./apic -s <platform_endpoint_url> apps:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> app.yaml

    Datendatei: Erstellen Sie eine YAML-Datei mit dem Namen app.yaml und folgendem Inhalt:

    name: apppreview

    Beispiel:

    ./apic -s platform-api.us-east-a.apiconnect.automation.ibm.com apps:create -o lwgw-demo -c previewcatalog --consumer-org previewCorg app.yaml
  2. Erstellen Sie ein Abonnement mit Hilfe der Datei subscription.yaml (Sie müssen die App erstellen, bevor Sie ein Abonnement erstellen können):
    ./apic -s <platform_endpoint_url> subscriptions:create -o <org_name> -c <catalog_name> --consumer-org <consumer_org_name> --app <app_name>
    Erzeugen Sie die Datendatei: subscription.yaml
    Hinweis: Dieses Kommando identifiziert das Stufenprodukt, das die Client-Anwendung abonniert.
    echo "{product_url: $PRODUCT_URL, plan: default-plan}" > subscription.yaml

    Beispiel:

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

Überprüfen Sie, ob Ihre Befehle funktioniert haben

Überprüfen Sie die Ergebnisse Ihrer Befehle auf dem Gateway. Hier sehen Sie, ob alle Befehle ausgeführt wurden oder ob noch welche ausstehen.

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

Beispiel:

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

Testen Sie die API mit dem Lightweight Gateway

Verwenden Sie curl, um einige schnelle API-Aufrufe durchzuführen und zu sehen, wie sich Lightweight Gateway verhält.

Kopieren Sie jeden Befehl und führen Sie ihn aus:
Hinweis: Das endpoint muss den Namen Ihres Katalogs, den Produktnamen und den Namen der Anbieterorganisation in folgendem Format enthalten: http://{product}-{catalog}-{org}.{gateway_name}.rosa.apic-v-lw01.lugt.p3.openshiftapps.com/{version}/{server_url}/{path}
  • Schlechte Anfrage - Anfrage wird nicht geparst
    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

    Diese Anfrage ist eine fehlerhafte Anfrage, weil die Endung ] im Array fehlt und die Anfrage nicht geparst werden kann.

  • Schlechte Anfrage - Anfrage wird nicht validiert
    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

    Dies ist eine schlechte Anfrage, denn obwohl das Array korrekt formatiert ist, schreibt das Anfrageschema vor, dass die geposteten Daten ein JSON-Objekt sein müssen (kein Array).

  • Gültige Antwort
    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

    Dies ist eine gültige Antwort, da der Format-Header als Zeichenkette simple von httpbin.org zurückgegeben wird, was der Anforderung des Antwortschemas entspricht, dass /headers/Format den Enum-Einschränkungen von simple oder complex entsprechen muss.