Wrapper-APIs bereitstellen

Oracle Blockchain Platform Digital Assets Edition kann Wrapper-APIs für alle Controller-APIs in Chaincode generieren, der von Blockchain App Builder generiert wird. Gehen Sie folgendermaßen vor, um das Wrapper-API-Package im Stack Resource Manager bereitzustellen und die Wrapper-APIs mit der zugehörigen Postman-Collection zu testen.

Wenn Sie ein Wrapper-API-Package mit Blockchain App Builder generieren, werden zwei Dateien mit Standardbenennungskonventionen im ausgewählten Verzeichnis erstellt:

  • <ChaincodeName>WrapperAPI.zip: Eine Archivdatei, die das Terraform-Skript enthält, das zum Deployment der Wrapper-APIs in Oracle Cloud Infrastructure (OCI) Resource Manager erforderlich ist.
  • <ChaincodeName>_WrapperAPI.postman_collection.json: Eine Postman-Collection, mit der die Wrapper-APIs nach dem Deployment getestet werden.

Um die Wrapper-APIs bereitzustellen, erstellen Sie mit der Datei WrapperAPI.zip einen Stack in OCI Resource Manager.

Die folgenden Voraussetzungen müssen erfüllt sein, um das Wrapper-API-Package bereitzustellen.

  • Das Wrapper-API-Package muss mit Blockchain App Builder generiert werden.
  • Das Package muss alle erforderlichen Konfigurationsvariablenwerte und Endpunktwerte für die Wrapper-APIs enthalten.
  1. Bei OCI anmelden.
    Öffnen Sie die OCI-Konsole, und melden Sie sich an: https://cloud.oracle.com/. Stellen Sie sicher, dass Sie sich im Compartment befinden, in dem der Stack bereitgestellt wird.
  2. Blenden Sie das Menü Navigation ein. Wählen Sie Developer Services aus. Wählen Sie unter Resource Manager die Option Stacks aus.
    Die Resource Manager-Benutzeroberfläche für Stacks wird geöffnet. Sie können vorhandene Stacks anzeigen, Stacks erstellen und Ihre Infrastruktur mit Terraform-Konfigurationen als Code verwalten.
  3. Klicken Sie auf Stack erstellen.
  4. Konfigurieren Sie die Stackinformationen.
    1. Wählen Sie im Abschnitt Terraform-Konfiguration die Option Meine Konfiguration aus.
    2. Wählen Sie unter Stackkonfiguration, Terraform-Konfigurationsquelle, Zip-Datei aus.
    3. Klicken Sie auf Durchsuchen, und navigieren Sie zur Datei .zip der Wrapper-API.
    4. Stellen Sie nach dem Hochladen der Datei .zip sicher, dass der Stapelname korrekt ist.
    5. Wählen Sie in der Dropdown-Liste Terraform-Version "v1.2" oder höher aus. Standardmäßig verwendet Resource Manager die neueste Version. Wenn Sie eine Version vor Version 1.2 auswählen, verläuft das Deployment nicht erfolgreich.
    6. Alle verbleibenden Einstellungen können standardmäßig beibehalten werden. Klicken Sie auf Weiter.
  5. Konfigurieren Sie die Stackvariablen.
    1. Prüfen Sie, ob alle Werte der Konfigurationsvariablen korrekt sind, und richten Sie sie an die im Wrapper-API-Package angegebenen Konfigurationsvariablen aus, um die Anforderungen für Ihr Deployment zu erfüllen.
    2. Geben Sie unter ocir_user_name die E-Mail-Adresse ein, die Ihrem OCI-Account zugeordnet ist.
    3. Geben Sie unter ocir_user_password Ihr Kennwort ein. Dies ist Ihr OCI-Authentifizierungstoken. Sie können dieses Token im Abschnitt "Profil" oder "Benutzereinstellungen" der OCI-Konsole generieren. Das Authentifizierungstoken dient als Kennwort für die Anmeldung bei Oracle Cloud Infrastructure Registry.
      Weitere Informationen zum Generieren eines Authentifizierungstokens finden Sie unter Authentifizierungstoken generieren.
    4. Alle verbleibenden Einstellungen können standardmäßig beibehalten werden. Klicken Sie auf Weiter.
  6. Prüfen Sie die Stackinformationen. Wenn alles korrekt ist, klicken Sie auf Erstellen.
  7. Terraform-Plan ausführen
    1. Klicken Sie auf der Seite Details des Stacks auf Planen, um mit dem Erstellen eines Ausführungsplans zu beginnen.
    2. Konfigurieren Sie optional den Jobplan. Sie können den Standardnamen bearbeiten oder erweiterte Optionen auswählen, um die Providerversion zu ändern oder Einstellungen anzupassen.
    3. Klicken Sie auf Planen, um den Planjob zu erstellen und auszuführen.
      Ihre Terraform-Konfiguration wird geparst, und ein Ausführungsplan wird generiert und ausgeführt. Dadurch werden die folgenden Aufgaben abgeschlossen:
      • Validiert das Terraform-Skript, um sicherzustellen, dass keine Syntax- oder Konfigurationsfehler vorliegen.
      • Simuliert den Ressourcenerstellungsprozess, ohne Änderungen an der tatsächlichen Infrastruktur vorzunehmen.
      • Stellt eine Ausgabeübersicht bereit, in der die Ressourcen aufgeführt werden, die das Skript erstellt, ändert oder zerstört.
    4. Überwachen Sie den Status im Abschnitt Jobs des Stacks. Nachdem der Plan erfolgreich abgeschlossen wurde, prüfen Sie die Ausgabe, um die Anzahl der zu erstellenden Ressourcen zu bestätigen und sicherzustellen, dass keine Probleme auftreten.
  8. Wenden Sie den Terraform-Plan auf den Stack an.
    1. Klicken Sie auf der Seite Details des Stacks auf Anwenden.
    2. Klicken Sie im Bereich Terraform anwenden auf Anwenden.
      Durch das Anwenden des Terraform-Plans werden die folgenden Aufgaben ausgeführt:
      • Stellt alle folgenden Ressourcen bereit, wie im Terraform-Skript definiert:
        • Virtuelles Cloud-Netzwerk (VCN)
        • Anwendungen (OCI Functions)
        • API-Gateway
        • API-Deployment
        • IAM-Policy
        • OCI Registry-Repository
      • Erstellt die gesamte erforderliche Infrastruktur für die Wrapper-APIs.
    3. Überwachen Sie den Status im Abschnitt Jobs des Stacks, um sicherzustellen, dass der Job ohne Fehler erfolgreich abgeschlossen wird.
  9. Rufen Sie die API-Gateway-Endpunkte ab.
    1. Nach Abschluss des Jobs "Anwenden" können Sie auf der Seite Job anwenden im Abschnitt Ausgaben die generierten Ausgabewerte anzeigen.
    2. Die Ausgabe gibt ein JSON-Objekt zurück, bei dem die Schlüssel Endpunktnamen darstellen und die Werte die entsprechenden Endpunktwerte sind:
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. Kopieren Sie den Endpunkt. Sie benötigen den Endpunkt, um die API-Postman-Sammlung zu aktualisieren.
Wrapper-APIs mit Postman testen

Sie können die Wrapper-APIs mit Postman testen. Konfigurieren Sie alle Variablen in der Postman-Collection der Wrapper-API, indem Sie die entsprechenden Werte zuweisen. Rufen Sie den Wert api_gateway_endpoint aus der Ausgabe des Stack-Deployments in OCI ab, in dem die dynamisch generierten Gatewayendpunkte bereitgestellt werden.

Nachdem die Variablen in der Postman-Collection aktualisiert wurden, können Sie die Wrapper-APIs testen. Jede API-Anforderung in der Collection enthält die erforderliche Payload speziell für die entsprechende Wrapper-API.

Abbildung 4-1: API-Wrapper-Sammlung mit Postman testen


Das Bild zeigt, wie Postman eine API aus der Sammlung mit der generierten Gateway-API ausführt.

Mit den folgenden Informationen können Sie Probleme beim Deployment und der Verwendung von Wrapper-APIs beheben.

Nicht autorisiert: Ungültige ocir_user_name oder ocir_user_password
Dieser Fehler tritt auf, wenn der Benutzername oder die Kennwortzugangsdaten falsch sind. Zur Lösung dieses Problems führen Sie die folgenden Schritte aus:
  1. Navigieren Sie auf der Seite Details des Stacks zum Abschnitt Variablen.
  2. Klicken Sie auf Variablen bearbeiten, um den Benutzernamen und das Kennwort zu ändern.
  3. Aktualisieren Sie die Zugangsdaten mit den richtigen Informationen.
  4. Klicken Sie auf Anwenden, um den Stack erneut bereitzustellen.
Deployment-Fehler - "denied: Anonyme Benutzer haben nur Lesezugriff auf öffentliche Repositorys"
Gelegentlich kann das Deployment mit dem folgenden Fehler fehlschlagen:
denied: Anonymous users are only allowed read access on public repos

Dies ist ein intermittierendes Problem, das sich auf Docker-Vorgänge im Backend des Stacks bezieht. Dieser Fehler tritt insbesondere auf, wenn versucht wird, Docker-Images ohne ordnungsgemäße Authentifizierung an die Oracle Cloud Infrastructure Registry zu übertragen.

Während das Wrapper-API-Package ein Skript enthält, das den Befehl docker login ausführt, um die ordnungsgemäße Authentifizierung vor dem Übertragen der Images sicherzustellen, kann dieser Fehler immer noch sporadisch auftreten. Dies geschieht normalerweise, wenn der Docker-Authentifizierungsschritt zum Zeitpunkt des Imagepushs vom System nicht ordnungsgemäß erkannt wird.

Wenn dieser Fehler auftritt, führen Sie die folgenden Schritte aus, um das Problem zu lösen:

  1. Klicken Sie im OCI Stack Resource Manager auf Zerstören, um alle Ressourcen zu löschen, die während des Deployment-Prozesses erstellt wurden.
  2. Nachdem die Ressourcen gelöscht wurden, klicken Sie erneut auf Anwenden, um den Stack erneut bereitzustellen. Dadurch wird die Erstellung der erforderlichen Ressourcen ausgelöst, einschließlich der richtigen Docker-Authentifizierung.
Generischer Deployment-Fehler: Intermittierende Probleme
Das Stack-Deployment kann manchmal aufgrund zufälliger Docker-Probleme fehlschlagen. Führen Sie in diesem Fall die folgenden Schritte aus, um das Problem zu lösen:
  1. Klicken Sie auf Löschen, um alle Ressourcen zu entfernen, die während des nicht erfolgreichen Deployments erstellt wurden.
  2. Nachdem die Ressourcen gelöscht wurden, navigieren Sie zurück zum Stack, und klicken Sie auf Anwenden, um den Stack erneut bereitzustellen.

Dies kann zeitweise auftretende Probleme lösen und ein erfolgreiches Deployment ermöglichen.