Implantar APIs Wrapper

A Edição de Ativos Digitais do Oracle Blockchain Platform permite a geração de APIs wrapper para todas as APIs do controlador dentro do chaincode gerado pelo App Builder. Este tópico fornece etapas detalhadas para implantar o pacote de APIs do wrapper no gerenciador de recursos de pilha e testar as APIs do wrapper usando a coleção Postman associada.

Quando o pacote de API do wrapper é gerado usando o Blockchain App Builder, ele cria dois arquivos com convenções de nomenclatura padrão no diretório escolhido:

1. <ChaincodeName>WrapperAPI.zip: Este arquivo contém o script do Terraform necessário para implantar as APIs do encapsulador no Oracle Cloud Infrastructure Resource Manager.
2. <ChaincodeName>_WrapperAPI.postman_collection.json: Uma coleção Postman usada para testar as APIs do wrapper após a implantação.

Para implantar as APIs wrapper, o arquivo WrapperAPI.zip deve ser usado no OCI Resource Manager.

Pré-requisitos

Os pré-requisitos para implantar o pacote de APIs wrapper são os seguintes:

• O pacote de APIs do wrapper deve ser gerado usando o App Builder.
• O pacote deve incluir todos os valores de variáveis de configuração e valores de ponto final necessários para as APIs do wrapper.

Implantando o pacote de API do Wrapper

1. Faça log-in no OCI.
   Abra o console do OCI e acesse: https://cloud.oracle.com/.
   Certifique-se de que você esteja no compartimento no qual a pilha será implantada.
2. Expanda o menu Navegação. Selecione Developer Services. Em Resource Manager, selecione Pilhas.
   A interface do Resource Manager para pilhas é aberta. Você pode exibir pilhas existentes, criar novas pilhas e gerenciar sua infraestrutura como código usando configurações do Terraform.
3. Crie uma nova pilha clicando em Criar Pilha.
4. Configure as informações da pilha.
   1. Na seção Configuração do Terraform, selecione Minha Configuração.
   2. Em Configuração da Pilha, Origem da configuração do Terraform, selecione o arquivo.Zip.
   3. Clique em Procurar e navegue até o arquivo Zip de APIs do wrapper.
   4. Após o upload, verifique se o nome da pilha está correto.
   5. Todas as configurações restantes podem ser mantidas como padrão. Clique em Próximo.
5. Configure as variáveis de pilha.
   1. Verifique se todos os valores de variáveis de configuração são precisos e alinhados com as variáveis de configuração especificadas no pacote de API do wrapper para atender aos requisitos da sua implantação.
   2. Em ocir_user_name, digite o endereço de e-mail associado à sua conta do OCI.
   3. Em ocir_user_password, digite sua senha, que é o seu Token de Autenticação do Oracle Cloud Infrastructure. Esse token pode ser gerado na console do OCI sob suas definições de usuário. O Token de Autenticação serve como uma senha para fazer log-in no Oracle Cloud Infrastructure Registry (OCIR).
      Para obter instruções detalhadas sobre como gerar o Token de Autenticação, consulte Gerando um Token de Autenticação.
   4. Todas as configurações restantes podem ser mantidas como padrão. Clique em Próximo.
6. Verifique as informações da pilha. Se tudo estiver correto, clique em Criar.
7. Execute o plano do Terraform.
   1. Na página Detalhes da pilha, clique em Planejar para iniciar a criação de um plano de execução.
   2. Opcionalmente, configure o plano de jobs. Você pode editar o nome padrão ou selecionar opções avançadas para alterar a versão do provedor das definições de ajuste.
   3. Clique em Plano para criar e executar o job de planejamento.
      Isso fará parsing da configuração do Terraform, gerará um plano de execução e executará o plano que faz o seguinte:

      • Valida o script do Terraform para garantir que não haja erros de sintaxe ou configuração.
      • Simula o processo de criação de recursos sem fazer alterações na infraestrutura real.
      • Fornece um resumo de saída que lista os recursos que o script pretende criar, modificar ou destruir.
   4. Monitore o status na seção Jobs da sua pilha. Depois que o plano for concluído com sucesso, revise a saída para confirmar o número de recursos que serão criados e verifique se não há problemas.
8. Aplique o plano do Terraform à pilha.
   1. Na página Detalhes da pilha, clique em Aplicar.
   2. No painel Aplicar do Terraform, clique em Aplicar.
      Isso fará o seguinte:

      • Provisiona todos os seguintes recursos conforme definido no script Terraform:
        • Rede virtual na nuvem (VCN)
        • Aplicativos (Funções do OCI)
        • Gateway de API
        • Implantação da API
        • Política do serviço IAM
        • Repositório do OCI Registry
      • Cria toda a infraestrutura necessária para as APIs do Wrapper.
   3. Monitore o status na seção Jobs da sua pilha para garantir que o job seja concluído com sucesso sem erros.
9. Recupere os pontos finais do Gateway de API.
   1. Depois que o job Aplicar for concluído, vá para a seção Saídas da página do job Aplicar para exibir os valores de saída gerados.
   2. A saída retornará um objeto JSON em que as chaves representam nomes de ponto final e os valores são seus valores de ponto final correspondentes.
      Por exemplo:

      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}

   3. Copie o ponto final - é necessário atualizar a coleção API Postman.

Testando APIs Wrapper com Postman

Você pode testar as APIs no Postman. Configure todas as variáveis na coleção Postman da API do wrapper atribuindo os valores apropriados. O valor api_gateway_endpoint deve ser obtido da saída da implantação de pilha no OCI, na qual os pontos finais de gateway gerados dinamicamente serão fornecidos.

Depois que as variáveis na coleção Postman forem atualizadas, você poderá testar as APIs do wrapper. Cada solicitação de API na coleção inclui o payload necessário específico para a API do wrapper correspondente.

Figura 6-1 Testando uma Coleção de Wrapper de API com Postman

Solução de Problemas

A seguir estão alguns problemas comumente encontrados e suas soluções.

Não autorizado: ocir_user_name ou ocir_user_password inválido

Este erro ocorre quando as credenciais de nome de usuário ou senha estão incorretas. Para resolver esse problema, siga estas etapas:

1. Navegue até a seção Variáveis na página Detalhes da pilha.
2. Clique em Editar Variáveis para modificar os valores de nome de usuário e senha.
3. Atualize as credenciais com as informações corretas.
4. Depois que as alterações forem feitas, clique em Aplicar para reimplantar a pilha.

Isso deve resolver o problema de autenticação e permitir que a implantação continue com sucesso.

Falha na Implantação - "negado: usuários anônimos só têm permissão de acesso de leitura em repositórios públicos"

Ocasionalmente, a implantação pode falhar com o seguinte erro:

denied: Anonymous users are only allowed read access on public repos

Este é um problema intermitente relacionado às operações do Docker no backend da pilha. Especificamente, esse erro ocorre ao tentar enviar imagens do Docker para o Oracle Cloud Infrastructure Registry (OCIR) sem a autenticação adequada.

Embora o pacote de API do wrapper inclua um script que execute docker login antes de enviar as imagens, garantindo a autenticação adequada, esse erro ainda pode ocorrer esporadicamente. Geralmente, isso acontece quando a etapa de autenticação do Docker não é reconhecida corretamente pelo sistema no momento do envio da imagem.

Se esse erro ocorrer, siga estas etapas para resolver o problema:

1. Destruir Recursos Existentes:

   Clique em Destruir no OCI Stack Resource Manager para destruir todos os recursos criados durante o processo de implantação.

2. Reaplicar a Pilha:

   Depois de destruir os recursos, clique em Aplicar novamente para reimplantar a pilha. Isso acionará a criação dos recursos necessários, incluindo a autenticação adequada do Docker, e deverá resolver o problema.

Falha na Implantação Genérica: Problemas Intermitentes

Às vezes, a implantação de pilha pode falhar devido a problemas aleatórios relacionados ao docker. Nesses casos, siga estas etapas para resolver o problema:

1. Clique em Destruir para remover todos os recursos criados durante a implantação com falha.
2. Depois que os recursos forem destruídos, navegue de volta para a pilha e clique em Aplicar para reimplantar a pilha.

Esse processo geralmente resolve problemas intermitentes, permitindo que a implantação continue com sucesso.