Implantar APIs do Wrapper

A Edição de Ativos Digitais do Oracle Blockchain Platform pode gerar APIs wrapper para todas as APIs controladoras em chaincode geradas pelo Blockchain App Builder. Siga as etapas abaixo para implantar o pacote de API do wrapper no gerenciador de recursos da pilha e testar as APIs do wrapper usando a coleção Postman associada.

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

  • <ChaincodeName>WrapperAPI.zip: Um arquivo compactado que contém o script Terraform necessário para implantar as APIs do wrapper no Oracle Cloud Infrastructure (OCI) Resource Manager.
  • <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 do encapsulador, use o arquivo WrapperAPI.zip para criar uma pilha no OCI Resource Manager.

Os pré-requisitos a seguir devem ser atendidos para implantar o pacote de API do encapsulador.

  • O pacote da API wrapper deve ser gerado usando o Blockchain 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 encapsulador.
  1. Faça login no OCI.
    Abra a console do OCI e acesse: https://cloud.oracle.com/. Certifique-se de estar no compartimento no qual a pilha será implantada.
  2. Expanda o menu de Navegação. Selecione Serviços do Desenvolvedor. Em Resource Manager, selecione Pilhas.
    A interface do Resource Manager para pilhas é aberta. Você pode exibir pilhas existentes, criar pilhas e gerenciar sua infraestrutura como código usando as configurações do Terraform.
  3. Clicar 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 de Pilha, Origem de configuração do Terraform, selecione arquivo .Zip.
    3. Clique em Procurar e navegue até o arquivo .zip da API do wrapper.
    4. Depois que o arquivo .zip for submetido a upload, certifique-se de que o nome da pilha esteja correto.
    5. Na lista drop-down Versão do Terraform, selecione v1.2 ou mais recente. Por padrão, o Resource Manager usa a versão mais recente. Se você selecionar uma versão anterior à v1.2, a implantação falhará.
    6. 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 se alinham às variáveis de configuração especificadas no pacote de API do encapsulador 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. Para ocir_user_password, informe sua senha, que é seu token de autenticação do OCI. Você pode gerar esse token na seção de perfil ou definições do usuário da console do OCI. O token de autenticação funciona como uma senha para fazer log-in no Oracle Cloud Infrastructure Registry.
      Para obter mais informações sobre como gerar um 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 Plano para começar a criar um plano de execução.
    2. Opcionalmente, configure o plano de cargos. Você pode editar o nome padrão ou selecionar opções avançadas para alterar a versão do provedor ou ajustar as definições.
    3. Clique em Plano para criar e executar o job de planejamento.
      A configuração do Terraform é analisada e um plano de execução é gerado e executado, o que conclui as seguintes tarefas:
      • 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 criará, modificará ou destruirá.
    4. Monitore o status na seção Jobs da sua pilha. Após a conclusão bem-sucedida do plano, revise a saída para confirmar o número de recursos que serão criados e para verificar 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 Terraform, clique em Aplicar.
      A aplicação do plano do Terraform conclui as seguintes tarefas:
      • Provisiona todos os recursos a seguir, conforme definido no script do Terraform:
        • Rede virtual na nuvem (VCN)
        • Aplicativos (Funções do OCI)
        • Gateway da API
        • Implantação da API
        • Política de 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 API Gateway.
    1. Depois que o job de aplicação for concluído, vá para a seção Saídas da página Aplicar job para exibir os valores de saída gerados.
    2. A saída retorna um objeto JSON em que as chaves representam nomes de ponto final e os valores são seus valores de ponto final correspondentes:
      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
    3. Copie o ponto final. Você precisa do ponto final para atualizar a coleção Postman da API.
Testando APIs do Wrapper com o Postman

Você pode testar as APIs do wrapper usando o Postman. Configure todas as variáveis na coleção Postman da API do wrapper, atribuindo os valores apropriados. Obtenha o valor api_gateway_endpoint da saída da implantação de pilha no OCI, em que os pontos finais de gateway gerados dinamicamente sã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 wrapper correspondente.

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


A imagem mostra o Postman executando uma API da coleção usando a API de gateway gerada.

As informações a seguir podem ser usadas para diagnosticar e solucionar problemas ao implantar e usar APIs do wrapper.

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. Clique em Aplicar para reimplantar a pilha.
Falha de 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 back-end da pilha. Especificamente, esse erro ocorre ao tentar enviar imagens do Docker ao Oracle Cloud Infrastructure Registry sem autenticação adequada.

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

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

  1. Clique em Destruir no OCI Stack Resource Manager para destruir todos os recursos que foram criados durante o processo de implantação.
  2. Após a destruição dos recursos, clique em Aplicar novamente para reimplantar a pilha. Isso aciona a criação dos recursos necessários, incluindo a autenticação adequada do Docker.
Falha de Implantação Genérica: Problemas Intermitentes
Às vezes, a implantação de pilha pode falhar por causa de problemas aleatórios relacionados ao Docker. Quando isso acontecer, siga estas etapas para resolver o problema:
  1. Clique em Destruir para remover todos os recursos que foram criados durante a implantação com falha.
  2. Após a destruição dos recursos, navegue de volta para a pilha e clique em Aplicar para reimplantar a pilha.

Isso pode resolver problemas intermitentes e permitir uma implantação bem-sucedida.