Déployer les API d'encapsuleur

La solution Oracle Blockchain Platform Digital Assets Edition peut générer des API de wrapper pour toutes les API de contrôleur dans le code de chaîne généré par Blockchain App Builder. Effectuez les étapes suivantes pour déployer l'ensemble d'API d'encapsuleur dans le gestionnaire de ressources de pile et tester les API d'encapsuleur à l'aide de la collection Postman associée.

Lorsque vous générez un package d'API wrapper à l'aide de Blockchain App Builder, il crée deux fichiers avec des conventions de dénomination par défaut dans le répertoire choisi :

  • <ChaincodeName>WrapperAPI.zip : Fichier d'archives contenant le script Terraform requis pour déployer les API d'encapsuleur dans le gestionnaire de ressources pour Oracle Cloud Infrastructure (OCI).
  • <ChaincodeName>_WrapperAPI.postman_collection.json : Collection Postman utilisée pour tester les API d'encapsuleur après le déploiement.

Pour déployer les API d'encapsuleur, vous utilisez le fichier WrapperAPI.zip pour créer une pile dans le gestionnaire de ressources OCI.

Les préalables suivants doivent être respectés pour déployer l'ensemble d'API d'encapsuleur.

  • L'ensemble d'API d'encapsulation doit être généré à l'aide du générateur d'applications Blockchain.
  • Le paquetage doit inclure toutes les valeurs de variable de configuration et de point d'extrémité requises pour les API d'encapsuleur.
  1. Connectez-vous à OCI.
    Ouvrez la console OCI et connectez-vous à l'adresse https://cloud.oracle.com/. Assurez-vous d'être dans le compartiment où la pile sera déployée.
  2. Développez le menu Navigation. Sélectionnez Services de développement. Sous Gestionnaire de ressources, sélectionnez Piles.
    L'interface du gestionnaire de ressources pour les piles s'ouvre. Vous pouvez voir les piles existantes, créer des piles et gérer votre infrastructure en tant que code à l'aide des configurations Terraform.
  3. Cliquez sur Créer une pile.
  4. Configurez les informations de la pile.
    1. Dans la section Configuration Terraform, sélectionnez Ma configuration.
    2. Dans Configuration de pile, Source de configuration Terraform, sélectionnez .Fichier zip.
    3. Cliquez sur Parcourir et naviguez jusqu'au fichier .zip de votre API d'encapsuleur.
    4. Une fois le fichier .zip chargé, assurez-vous que le nom de la pile est correct.
    5. Dans la liste déroulante Version de Terraform, sélectionnez v1.2 ou une version supérieure. Par défaut, le gestionnaire de ressources utilise la dernière version. Si vous sélectionnez une version antérieure à la version v1.2, le déploiement échouera.
    6. Tous les paramètres restants peuvent être conservés par défaut. Cliquez sur Suivant.
  5. Configurez les variables de pile.
    1. Vérifiez que toutes les valeurs des variables de configuration sont exactes et alignées avec les variables de configuration spécifiées dans le package d'API wrapper pour répondre aux exigences de votre déploiement.
    2. Pour ocir_user_name, entrez l'adresse de courriel associée à votre compte OCI.
    3. Pour ocir_user_password, entrez votre mot de passe, qui est votre jeton d'authentification OCI. Vous pouvez générer ce jeton dans la section du profil ou des paramètres d'utilisateur de la console OCI. Le jeton d'authentification fonctionne comme un mot de passe pour la connexion à Oracle Cloud Infrastructure Registry.
      Pour plus d'informations sur la génération d'un jeton d'authentification, voir Génération d'un jeton d'authentification.
    4. Tous les paramètres restants peuvent être conservés par défaut. Cliquez sur Suivant.
  6. Vérifiez les informations sur la pile. Si tout est correct, cliquez sur Créer.
  7. Exécutez le plan Terraform.
    1. Dans la page Détails de la pile, cliquez sur Planifier pour commencer à créer un plan d'exécution.
    2. Facultativement, configurez le plan de tâche. Vous pouvez modifier le nom par défaut ou sélectionner des options avancées pour modifier la version du fournisseur ou ajuster les paramètres.
    3. Cliquez sur Planifier pour créer et exécuter la tâche de planification.
      Votre configuration Terraform est analysée et un plan d'exécution est généré et exécuté, ce qui effectue les tâches suivantes :
      • Valide le script Terraform pour s'assurer qu'il n'y a aucune erreur de syntaxe ou de configuration.
      • Simule le processus de création des ressources sans apporter de modifications à l'infrastructure réelle.
      • Fournit un sommaire de sortie qui répertorie les ressources que le script créera, modifiera ou détruira.
    4. Surveillez le statut dans la section Tâches de votre pile. Une fois le plan terminé avec succès, vérifiez la sortie pour confirmer le nombre de ressources qui seront créées et pour vérifier qu'il n'y a aucun problème.
  8. Appliquez le plan Terraform à la pile.
    1. Dans la page Détails de la pile, cliquez sur Appliquer.
    2. Dans le panneau Appliquer Terraform, cliquez sur Appliquer.
      L'application du plan Terraform effectue les tâches suivantes :
      • Provisionne toutes les ressources suivantes, telles que définies dans le script Terraform :
        • Réseau en nuage virtuel (VCN)
        • Applications (fonctions OCI)
        • Passerelle d'API
        • Déploiement d'API
        • Politique GIA
        • Référentiel du registre OCI
      • Crée toute l'infrastructure requise pour les API d'encapsuleur.
    3. Surveillez le statut dans la section Tâches de votre pile pour vous assurer que la tâche s'est terminée avec succès, sans erreur.
  9. Extraire les points d'extrémité du service de passerelle d'API.
    1. Une fois la tâche d'application terminée, allez à la section Sorties de la page Appliquer la tâche pour voir les valeurs de sortie générées.
    2. La sortie retourne un objet JSON dans lequel les clés représentent les noms de point d'extrémité et les valeurs sont leurs valeurs de point d'extrémité correspondantes :
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. Copiez le point d'extrémité. Vous avez besoin du point d'extrémité pour mettre à jour la collection API Postman.
Test des API d'encapsuleur avec Postman

Vous pouvez tester les API du wrapper à l'aide de Postman. Configurez toutes les variables de la collection wrapper API Postman en affectant les valeurs appropriées. Obtenez la valeur api_gateway_endpoint à partir de la sortie du déploiement de pile dans OCI, où les points d'extrémité de passerelle générés dynamiquement sont fournis.

Une fois les variables de la collection Postman mises à jour, vous pouvez tester les API du wrapper. Chaque demande d'API de la collection inclut les données utiles nécessaires propres à l'API d'encapsulation correspondante.

Figure 4-1 Tester une collection d'encapsuleurs d'API avec Postman


Image représentant Postman exécutant une API à partir de la collection à l'aide de l'API de passerelle générée.

Les informations suivantes peuvent être utilisées pour résoudre les problèmes lors du déploiement et de l'utilisation des API wrapper.

Non autorisé : ocir_user_name ou ocir_user_password non valide
Cette erreur se produit lorsque les données d'identification du nom d'utilisateur ou du mot de passe sont incorrectes. Pour résoudre ce problème, procédez comme suit :
  1. Naviguez jusqu'à la section Variables de la page Détails de la pile.
  2. Cliquez sur Modifier les variables pour modifier les valeurs de nom d'utilisateur et de mot de passe.
  3. Mettez à jour les données d'identification avec les informations correctes.
  4. Cliquez sur Appliquer pour redéployer la pile.
Échec du déploiement - "Refusé : Les utilisateurs anonymes ne peuvent accéder en lecture que dans les référentiels publics"
Parfois, le déploiement peut échouer avec l'erreur suivante :
denied: Anonymous users are only allowed read access on public repos

Il s'agit d'un problème intermittent lié aux opérations Docker dans l'élément dorsal de la pile. Plus précisément, cette erreur se produit lors de la tentative de poussée d'images Docker vers Oracle Cloud Infrastructure Registry sans authentification appropriée.

Bien que l'ensemble d'API d'encapsuleur inclut un script qui exécute la commande docker login pour garantir une authentification appropriée avant de pousser les images, cette erreur peut toujours se produire sporadiquement. Cela se produit généralement lorsque l'étape d'authentification Docker n'est pas reconnue correctement par le système au moment de la poussée d'image.

Si cette erreur se produit, procédez comme suit pour résoudre le problème :

  1. Cliquez sur Détruire dans le gestionnaire de ressources de pile OCI pour détruire toutes les ressources qui ont été créées lors du processus de déploiement.
  2. Une fois les ressources détruites, cliquez de nouveau sur Appliquer pour redéployer la pile. Cela déclenche la création des ressources nécessaires, y compris l'authentification Docker appropriée.
Échec du déploiement générique : Problèmes intermittents
Le déploiement de la pile peut parfois échouer en raison de problèmes aléatoires liés à Docker. Lorsque cela se produit, procédez comme suit pour résoudre le problème :
  1. Cliquez sur Détruire pour supprimer toutes les ressources créées lors de l'échec du déploiement.
  2. Une fois les ressources détruites, revenez à la pile et cliquez sur Appliquer pour redéployer la pile.

Cela peut résoudre les problèmes intermittents et permettre un déploiement réussi.