Déployer des API d'encapsuleur

Oracle Blockchain Platform Digital Assets Edition permet la génération d'API d'encapsulation pour toutes les API de contrôleur dans le code de chaîne généré par le générateur d'applications. Cette rubrique décrit les étapes détaillées à suivre pour déployer le paquetage 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 le paquetage d'API wrapper est généré à 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 :

  1. <ChaincodeName>WrapperAPI.zip : Ce fichier contient le script Terraform requis pour déployer les API d'encapsuleur dans Oracle Cloud Infrastructure Resource Manager.
  2. <ChaincodeName>_WrapperAPI.postman_collection.json : Collection Postman utilisée pour tester les API d'encapsulation après le déploiement.

Pour déployer les API d'encapsuleur, le fichier WrapperAPI.zip doit être utilisé dans le gestionnaire de ressources OCI.

Conditions requises

Les préalables au déploiement de l'ensemble API wrapper sont les suivants :

  • Le paquetage d'API d'encapsuleur doit être généré à l'aide du générateur d'applications.
  • Le package doit inclure toutes les valeurs de variable de configuration et de point d'extrémité requises pour les API d'encapsulation.
Déploiement du package d'API Wrapper
  1. Connectez-vous à OCI.
    Ouvrez la console OCI et connectez-vous : 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, en créer de nouvelles et gérer votre infrastructure en tant que code à l'aide des configurations Terraform.
  3. Créez une nouvelle pile en cliquant sur Créer une pile.
  4. Configurez les informations sur la pile.
    1. Dans la section Configuration Terraform, sélectionnez Ma configuration.
    2. Dans Configuration de la pile, Source de la configuration Terraform, sélectionnez Fichier.Zip.
    3. Cliquez sur Parcourir et naviguez jusqu'au fichier zip des API d'encapsuleur.
    4. Une fois chargé, assurez-vous que le nom de la pile est correct.
    5. 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 qu'elles sont 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 Oracle Cloud Infrastructure. Ce jeton peut être généré dans la console OCI dans vos paramètres d'utilisateur. Le jeton d'authentification sert de mot de passe pour la connexion à Oracle Cloud Infrastructure Registry (OCIR).
      Pour des instructions détaillées sur la génération du 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 lancer la création d'un plan d'exécution.
    2. Facultativement, configurez le plan de travail. Vous pouvez modifier le nom par défaut ou sélectionner des options avancées pour modifier la version du fournisseur des paramètres d'ajustement.
    3. Cliquez sur Planifier pour créer et exécuter la tâche de plan.
      Cela analysera votre configuration Terraform, générera un plan d'exécution et exécutera le plan qui effectue les opérations suivantes :
      • Valide le script Terraform pour s'assurer qu'il n'y a pas d'erreur de syntaxe ou de configuration.
      • Simule le processus de création de ressources sans apporter de modifications à l'infrastructure réelle.
      • Fournit un sommaire de sortie qui répertorie les ressources que le script a l'intention de créer, modifier ou détruire.
    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 vérifiez 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.
      Ceci fera ce qui suit :
      • Provisionne toutes les ressources suivantes, telles que définies dans le script Terraform :
        • Réseau en nuage virtuel (VCN)
        • Applications (fonctions d'OCI)
        • Passerelle d'API
        • Déploiement d'API
        • Politique IAM
        • Référentiel du registre OCI
      • Crée toute l'infrastructure requise pour les API Wrapper.
    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. Extrayez 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 retournera un objet JSON où les clés représentent les noms de point d'extrémité et les valeurs sont leurs valeurs de point d'extrémité correspondantes.
      Par exemple :
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. Copiez le point d'extrémité - il est nécessaire de mettre à jour la collection API Postman.
Tester les API d'encapsuleur avec Postman

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

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

Figure 6-1 Test d'une collection d'emballage API avec Postman


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

Dépannage

Voici quelques problèmes fréquemment rencontrés et leurs solutions.

Non autorisé : ocir_user_name ou ocir_user_password non valides
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 :
  1. Naviguez jusqu'à la section Variables dans 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. Une fois les modifications apportées, cliquez sur Appliquer pour redéployer la pile.

Cela devrait résoudre le problème d'authentification et permettre au déploiement de se poursuivre avec succès.

Échec du déploiement - "Refusé : Les utilisateurs anonymes n'ont accès en lecture qu'aux référentiels publics"
Il peut arriver que le déploiement échoue 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 le serveur dorsal de la pile. Plus précisément, cette erreur survient lors de la tentative de poussée des images Docker vers Oracle Cloud Infrastructure Registry (OCIR) sans authentification appropriée.

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

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

  1. Détruire les ressources existantes :

    Cliquez sur Détruire dans le gestionnaire de ressources de pile OCI pour détruire toutes les ressources créées lors du processus de déploiement.

  2. Réappliquer la pile :

    Après avoir détruit les ressources, cliquez de nouveau sur Appliquer pour redéployer la pile. Cela déclenchera la création des ressources nécessaires, y compris une authentification Docker appropriée, et devrait résoudre le problème.

Échec du déploiement générique : Problèmes intermittents
Parfois, le déploiement de la pile peut échouer en raison de problèmes aléatoires tels que liés au docker. Dans de tels cas, suivez les étapes suivantes 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.

Ce processus résout souvent les problèmes intermittents, ce qui permet au déploiement de se poursuivre avec succès.