Distribuisci API wrapper

Oracle Blockchain Platform Digital Assets Edition è in grado di generare API wrapper per tutte le API controller in codice concatenato generato da Blockchain App Builder. Completare i passi riportati di seguito per distribuire il package API wrapper in Stack Resource Manager e per eseguire il test delle API wrapper utilizzando la raccolta Postman associata.

Quando si genera un pacchetto API wrapper utilizzando Blockchain App Builder, vengono creati due file con convenzioni di denominazione predefinite nella directory scelta:

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

Per distribuire le API wrapper, utilizzare il file WrapperAPI.zip per creare uno stack in OCI Resource Manager.

Per distribuire il package API wrapper è necessario soddisfare i prerequisiti riportati di seguito.

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

Eseguire il login a OCI.
Aprire la console OCI e connettersi: https://cloud.oracle.com/. Assicurarsi di trovarsi nel compartimento in cui verrà distribuito lo stack.
Espandere il menu Navigazione. Selezionare Servizi per sviluppatori. In Resource Manager, selezionare Stack.
Viene visualizzata l'interfaccia di Resource Manager per gli stack. Puoi visualizzare gli stack esistenti, creare stack e gestire l'infrastruttura sotto forma di codice utilizzando le configurazioni Terraform.
Fare 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 dell'API wrapper.
4. Dopo aver caricato il file .zip, assicurarsi che il nome dello stack sia corretto.
5. Nell'elenco a discesa Versione Terraform selezionare la versione 1.2 o successiva. Per impostazione predefinita, Resource Manager utilizza la versione più recente. Se si seleziona una versione precedente alla v1.2, la distribuzione non riuscirà.
6. Tutte le impostazioni rimanenti possono essere mantenute come predefinite. Fare clic su Avanti.
Configurare le variabili di stack.
1. Verificare che tutti i valori delle variabili di configurazione siano accurati e che siano allineati alle variabili di configurazione specificate nel package 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 OCI. È possibile generare questo token nella sezione delle impostazioni del profilo o dell'utente della console OCI. Il token di autenticazione funge da password per il login a Oracle Cloud Infrastructure Registry.
  Per ulteriori informazioni sulla generazione di un token di autenticazione, vedere Generazione di un token di autenticazione.
4. Tutte le impostazioni rimanenti possono essere mantenute come predefinite. Fare clic su Avanti.
Rivedere 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 mansione. È possibile modificare il nome predefinito o selezionare le opzioni avanzate per modificare la versione del provider o modificare le impostazioni.
3. Fare clic su Piano per creare ed eseguire il job del piano.
  La configurazione Terraform viene analizzata e viene generato ed eseguito un piano di esecuzione che completa i task riportati 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 di output che elenca le risorse che lo script creerà, modificherà o eliminerà.
4. Monitorare lo stato nella sezione Job dello stack. Una volta completato correttamente il piano, esaminare l'output per confermare il numero di risorse che verranno create e per 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 Applica Terraform, fare clic su Applica.
  L'applicazione del piano Terraform completa i task riportati di seguito.
  - Esegue il provisioning di tutte le risorse seguenti, come definito nello script Terraform:
    - Rete cloud virtuale (VCN)
    - Applicazioni (funzioni OCI)
    - Gateway API
    - Distribuzione API
    - Criterio 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 venga completato correttamente senza errori.
Recupera gli endpoint del gateway API.
1. Al termine dell'applicazione del job, andare alla sezione Output della pagina Applica job per visualizzare i valori di output generati.
2. L'output restituisce un oggetto JSON in cui le chiavi rappresentano i nomi degli endpoint e i valori sono i valori endpoint corrispondenti:
```
api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}
```
3. Copiare l'endpoint. È necessario l'endpoint per aggiornare la raccolta API Postman.

Test delle API wrapper con Postman

È possibile eseguire il test delle API wrapper utilizzando Postman. Configurare tutte le variabili nella raccolta Postman API wrapper assegnando i valori appropriati. Ottenere il valore api_gateway_endpoint dall'output della distribuzione dello stack in OCI, in cui vengono forniti gli endpoint del gateway generati in modo dinamico.

Dopo l'aggiornamento delle variabili nella raccolta Postman, è possibile eseguire il test delle API wrapper. Ogni richiesta API nella raccolta include il payload necessario specifico dell'API wrapper corrispondente.

Figura 4-1 Test di una raccolta di wrapper API con Postman

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

Le informazioni riportate di seguito possono essere utilizzate per risolvere i problemi durante la distribuzione e l'utilizzo delle API wrapper.

Non autorizzato: ocir_user_name o ocir_user_password non validi

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

Passare alla sezione Variabili nella pagina Dettagli dello stack.
Fare clic su Modifica variabili per modificare i valori di nome utente e password.
Aggiornare le credenziali con le informazioni corrette.
Fare clic su Applica per ridistribuire lo stack.

Errore di distribuzione: "negato: agli utenti anonimi è consentito solo l'accesso in lettura ai repository pubblici"

È possibile che la distribuzione non riesca 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 back-end dello stack. In particolare, questo errore si verifica quando si tenta di eseguire il push delle immagini Docker in Oracle Cloud Infrastructure Registry senza l'autenticazione appropriata.

Sebbene il pacchetto API wrapper includa uno script che esegue il comando docker login per garantire l'autenticazione corretta prima di eseguire il push delle immagini, questo errore può comunque verificarsi sporadicamente. In genere si verifica quando il passo di autenticazione Docker non viene riconosciuto correttamente dal sistema al momento del push dell'immagine.

Se si verifica questo errore, effettuare le operazioni riportate di seguito per risolvere il problema.

Fare clic su Elimina in OCI Stack Resource Manager per eliminare tutte le risorse create durante il processo di distribuzione.
Dopo aver eliminato le risorse, fare di nuovo clic su Applica per ridistribuire lo stack. In questo modo si attiva la creazione delle risorse necessarie, inclusa l'autenticazione Docker appropriata.

Errore di distribuzione generico: problemi intermittenti

La distribuzione dello stack a volte può non riuscire a causa di problemi casuali correlati a Docker. In questo caso, effettuare le operazioni riportate di seguito per risolvere il problema.

Fare clic su Elimina per rimuovere tutte le risorse create durante la distribuzione non riuscita.
Dopo l'eliminazione delle risorse, tornare allo stack e fare clic su Applica per ridistribuire lo stack.

Ciò può risolvere problemi intermittenti e consentire una distribuzione riuscita.