Distribuisci API wrapper

Oracle Blockchain Platform Digital Assets Edition consente la generazione di API wrapper per tutte le API del controller all'interno del codice concatenato generato da App Builder. In questo argomento vengono descritti i passi dettagliati per la distribuzione del package API wrapper nel Resource Manager dello stack e per il test delle API wrapper utilizzando la raccolta Postman associata.

Quando il package API wrapper viene generato utilizzando Blockchain App Builder, crea due file con le convenzioni di denominazione predefinite nella directory scelta:

<ChaincodeName>WrapperAPI.zip: questo file contiene lo script Terraform necessario per distribuire le API wrapper in Oracle Cloud Infrastructure Resource Manager.
<ChaincodeName>_WrapperAPI.postman_collection.json: raccolta Postman utilizzata per eseguire il test delle API wrapper dopo la distribuzione.

Per distribuire le API wrapper, è necessario utilizzare il file WrapperAPI.zip in OCI Resource Manager.

Prerequisiti

Di seguito sono riportati i prerequisiti per la distribuzione del package API wrapper.

Il package API wrapper deve essere generato mediante App Builder.
Il pacchetto deve includere tutti i valori delle variabili di configurazione e gli endpoint necessari per le API wrapper.

Distribuzione del package API Wrapper

Eseguire il login a OCI.
Aprire la console OCI e accedere a: https://cloud.oracle.com/.

Assicurarsi di trovarsi nel compartimento in cui verrà distribuito lo stack.
Espandere il menu Navigazione. Selezionare Developer Services. In Gestione risorse, selezionare Stack.
Viene aperta l'interfaccia di Resource Manager per gli stack. Puoi visualizzare gli stack esistenti, creare nuovi stack e gestire la tua infrastruttura come codice utilizzando le configurazioni Terraform.
Creare un nuovo stack facendo clic su Crea stack.
Configurare le informazioni sullo stack.
1. Nella sezione Configurazione Terraform, selezionare Configurazione personale.
2. In Configurazione stack, Origine configurazione Terraform, selezionare file .zip.
3. Fare clic su Sfoglia e passare al file ZIP delle interfacce API del wrapper.
4. Una volta caricato, assicurarsi che il nome dello stack sia corretto.
5. Tutte le impostazioni rimanenti possono essere mantenute come predefinite. Fare clic su Avanti.
Configurare le variabili dello stack.
1. Verificare che tutti i valori delle variabili di configurazione siano accurati e che siano allineati alle variabili di configurazione specificate nel pacchetto API wrapper per soddisfare i requisiti per la distribuzione.
2. Per ocir_user_name, immettere l'indirizzo di posta elettronica associato all'account OCI.
3. Per ocir_user_password immettere la password, ovvero il token di autenticazione di Oracle Cloud Infrastructure. Questo token può essere generato nella console OCI nelle impostazioni utente. Il token di autenticazione funge da password per il login a Oracle Cloud Infrastructure Registry (OCIR).
  Per istruzioni dettagliate sulla generazione del token di autenticazione, vedere Generazione di un token di autenticazione.
4. Tutte le impostazioni rimanenti possono essere mantenute come predefinite. Fare clic su Avanti.
Esaminare le informazioni sullo stack. Se tutti i dati sono corretti, fare clic su Crea.
Eseguire il piano Terraform.
1. Nella pagina Dettagli dello stack, fare clic su Piano per avviare la creazione di un piano di esecuzione.
2. Facoltativamente, configurare il piano job. È possibile modificare il nome predefinito o selezionare le opzioni avanzate per modificare la versione del provider delle impostazioni di rettifica.
3. Fare clic su Piano per creare ed eseguire il job del piano.
  Questa operazione analizzerà la configurazione Terraform, genererà un piano di esecuzione ed eseguirà il piano che esegue le operazioni riportate di seguito.
  - Convalida lo script Terraform per assicurarsi che non vi siano errori di sintassi o di configurazione.
  - Simula il processo di creazione delle risorse senza apportare modifiche all'infrastruttura effettiva.
  - Fornisce un riepilogo dell'output in cui sono elencate le risorse che lo script intende creare, modificare o eliminare.
4. Monitorare lo stato nella sezione Job dello stack. Una volta completato correttamente il piano, rivedere l'output per confermare il numero di risorse che verranno create e verificare che non vi siano problemi.
Applicare il piano Terraform allo stack.
1. Nella pagina Dettagli dello stack, fare clic su Applica.
2. Nel pannello Applicazione Terraform, fare clic su Applica.
  Ciò comporta le operazioni riportate di seguito.
  - Esegue il provisioning di tutte le risorse seguenti in base a quanto definito nello script Terraform:
    - Rete cloud virtuale (VCN)
    - Applicazioni (funzioni OCI)
    - Gateway API
    - Distribuzione API
    - Criteri IAM
    - Repository registro OCI
  - Crea tutta l'infrastruttura necessaria per le API wrapper.
3. Monitorare lo stato nella sezione Job dello stack per assicurarsi che il job sia stato completato correttamente senza errori.
Recupera gli endpoint del gateway API.
1. Al termine del job di applicazione, andare alla sezione Output della pagina Applica job per visualizzare i valori di output generati.
2. L'output restituirà un oggetto JSON in cui le chiavi rappresentano i nomi degli endpoint e i valori sono i valori degli endpoint corrispondenti.
  Ad esempio:
```
api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
```
3. Copiare l'endpoint: è necessario aggiornare la raccolta API Postman.

Test delle API Wrapper con Postman

È possibile eseguire il test delle API in Postman. Configurare tutte le variabili nell'insieme Postman API wrapper assegnando i valori appropriati. Il valore api_gateway_endpoint deve essere ottenuto dall'output della distribuzione dello stack in OCI, dove verranno forniti gli endpoint del gateway generati dinamicamente.

Una volta aggiornate le variabili nella raccolta Postman, è possibile eseguire il test delle API wrapper. Ogni richiesta API nella raccolta include il payload necessario specifico per l'API wrapper corrispondente.

Figura 6-1 Test di una raccolta API Wrapper con Postman

Immagine che mostra Postman che esegue un'API dalla raccolta utilizzando l'API gateway generata.

Risoluzione dei problemi

Di seguito sono riportati alcuni problemi comuni e le relative soluzioni.

Non autorizzato: ocir_user_name o ocir_user_password non valido

Questo errore si verifica quando le credenziali del nome utente o della password sono errate. Per risolvere questo problema, attenersi alla procedura riportata di seguito.

Passare alla sezione Variabili della pagina Dettagli stack.
Fare clic su Modifica variabili per modificare i valori di nome utente e password.
Aggiornare le credenziali con le informazioni corrette.
Dopo aver apportato le modifiche, fare clic su Applica per ridistribuire lo stack.

Ciò dovrebbe risolvere il problema di autenticazione e consentire la distribuzione di procedere correttamente.

Errore di distribuzione - "Negato: agli utenti anonimi è consentito solo l'accesso in lettura sui repository pubblici"

A volte, la distribuzione potrebbe non riuscire con il seguente errore:

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

Si tratta di un problema intermittente correlato alle operazioni Docker nel backend dello stack. In particolare, questo errore si verifica quando si tenta di eseguire il push delle immagini Docker in Oracle Cloud Infrastructure Registry (OCIR) senza una corretta autenticazione.

Sebbene il pacchetto API wrapper includa uno script che esegue docker login prima di eseguire il push delle immagini, garantendo un'autenticazione corretta, questo errore può comunque verificarsi in modo sporadico. In genere si verifica quando il passo di autenticazione Docker non viene riconosciuto correttamente dal sistema al momento del push delle immagini.

Se si verifica questo errore, attenersi alla procedura riportata di seguito per risolvere il problema.

Elimina risorse esistenti:
Fare clic su Elimina in OCI Stack Resource Manager per eliminare tutte le risorse create durante il processo di distribuzione.
Riapplicare lo stack:
Dopo aver eliminato le risorse, fare di nuovo clic su Applica per ridistribuire lo stack. Ciò attiverà la creazione delle risorse necessarie, inclusa l'autenticazione Docker appropriata, e dovrebbe risolvere il problema.

Errore di distribuzione generico: problemi intermittenti

A volte, la distribuzione dello stack potrebbe non riuscire a causa di problemi casuali correlati al docker. In questi casi, attenersi alla procedura riportata di seguito per risolvere il problema.

Fare clic su Elimina per rimuovere tutte le risorse create durante la distribuzione non riuscita.
Una volta eliminate le risorse, tornare allo stack e fare clic su Applica per ridistribuire lo stack.

Questo processo spesso risolve problemi intermittenti, consentendo alla distribuzione di procedere correttamente.