Questo documento fornisce informazioni e risorse utili per aiutarti a sviluppare applicazioni SAP utilizzando la versione SAP BTP dell'SDK ABAP per Google Cloud.
Questo documento è rivolto agli sviluppatori SAP ABAP.
Per un elenco completo delle librerie client fornite dalla versione SAP BTP dell'SDK ABAP per Google Cloud, vedi SDK ABAP per le librerie client di Google Cloud.
Finestra singola di interazione
Ogni API Google Cloud abilitata nell'SDK ABAP per Google Cloud è rappresentata
da una classe ABAP, contenuta nel pacchetto /GOOG/CLIENT
. Una classe ABAP è composta da più metodi pubblici e ciascuno di questi metodi pubblici corrisponde a un metodo API Google Cloud. Ogni metodo pubblico è costituito inoltre da
parametri IMPORTING
e EXPORTING
. Una classe ABAP contiene anche
tipi di dati personalizzati, che possono essere utilizzati per creare e mappare i parametri IMPORTING
e EXPORTING
. Questi tipi di dati personalizzati vengono mappati alle definizioni dello schema dell'API.
Per ogni interazione con un'API Google Cloud di destinazione, la classe ABAP corrispondente agisce come unico punto di interazione. Questo concetto è chiamato finestra unica di interazione, che protegge tutte le complessità di fondo dell'interazione con un'API Google Cloud e presenta un'interfaccia semplificata. Questa interfaccia semplificata consente di concentrarsi sulle soluzioni aziendali sviluppate tramite l'SDK, senza preoccuparsi delle funzionalità sottostanti dell'SDK.
Flusso di interazione
Per chiamare un metodo API, devi utilizzare il seguente flusso di interazione:
- Connettersi a un'API.
- Crea una richiesta di input utilizzando i tipi ABAP.
- Chiama un metodo API.
- Analizza errori ed eccezioni.
- Leggi la risposta utilizzando i tipi ABAP.
stub del client API
Una tipica classe stub del client API è composta dalle seguenti sezioni:
- I tipi di ABAP mappati agli schemi dell'API. I tipi ABAP vengono usati per creare una richiesta di input e analizzare la risposta.
- Le costanti e gli attributi per l'utilizzo interno o esterno.
- I metodi API per interagire con le risorse API.
Funzionalità
L'SDK ABAP per Google Cloud include le seguenti funzionalità:
- Comunicazione HTTP: l'SDK stabilisce una connessione HTTP con gli endpoint API.
- Marshaling delle richieste: l'SDK converte i dati nei tipi ABAP in payload JSON che viene inviato come corpo della richiesta.
- Gestione di errori ed eccezioni: l'SDK gestisce i codici restituiti e i messaggi di errore restituiti dall'API e genera eventuali eccezioni.
- Risposta di demarshalling: l'SDK riconverti il payload JSON nel corpo della risposta nei tipi ABAP corrispondenti.
- Logging degli errori locale: l'SDK registra i messaggi di errore utilizzando il framework logging.
Progettazione delle API ed Explorer API di Google
Le API pubblicate da Google seguono la progettazione orientata alle risorse. Per scoprire di più sulla progettazione delle API di Google, consulta la guida alla progettazione delle API.
L'SDK ABAP per Google Cloud consente l'integrazione con le API basate su REST pubblicate da Google.
Explorer API di Google è uno strumento che consente di provare i metodi dell'API Google Cloud senza scrivere codice. Puoi utilizzare questo strumento per studiare le API e i parametri di input richiesti che vuoi passare ai relativi metodi ABAP corrispondenti.
Costrutti di codice
Spiega i costrutti del codice che utilizzi per creare i tuoi programmi ABAP utilizzando l'SDK ABAP per Google Cloud.
Costruttore
Innanzitutto, crei l'istanza della classe API che vuoi utilizzare. Il costruttore di ogni classe API avrebbe un pattern simile a quello mostrato nell'esempio seguente:
METHODS constructor IMPORTING !iv_key_name TYPE /goog/keyname OPTIONAL "Google Cloud Key Name !iv_log_obj TYPE balobj_d OPTIONAL "Application log: Object name !iv_log_subobj TYPE balsubobj OPTIONAL. "Application log: Subobject RAISING /goog/cx_sdk . "Exception Classes
Importazione dei parametri
La seguente tabella spiega i parametri di importazione di un costruttore di metodi:
Nome parametro | Tipo | Obbligatorio/Facoltativo | Descrizione |
---|---|---|---|
iv_key_name |
/GOOG/KEYNAME |
Obbligatorio | Specifica la chiave client dalla configurazione che utilizzi per creare una connessione a Google Cloud. Per informazioni sulla configurazione della chiave client, consulta Autenticazione. |
iv_log_object |
balobj_d |
Facoltativo | Specifica l'oggetto log dell'applicazione che utilizzi per archiviare gli errori generati dall'SDK. Per informazioni sulla configurazione del logging, vedi Logging delle applicazioni. |
iv_log_subobject |
balsubobj |
Facoltativo | Specifica l'oggetto secondario del log dell'applicazione, che utilizzi per archiviare gli errori generati dall'SDK. Per informazioni sulla configurazione del logging, vedi Logging delle applicazioni. |
Metodo API
Con la progettazione orientata alle risorse delle API Google Cloud, un metodo API è un'azione che può essere eseguita su una risorsa pubblicata dall'API.
Ad esempio, se Topics
è una risorsa pubblicata dall'API Pub/Sub, topics.get
è un metodo API che rappresenta un'azione sulla risorsa Topics
per ottenere la configurazione di un argomento.
Per mappare un metodo di classe ABAP a un metodo API,
puoi fare riferimento alla descrizione del metodo che segue il
pattern:<resource>.<method_verb>
.
Ad esempio, la descrizione di un metodo Pub/Sub è
pubsub.projects.topics.get
.
projects.topics
: il nome della risorsa.get
: l'azione del metodo.
Il nome di un metodo ABAP mappato a un'azione API segue lo schema:<method_verb>_<resource>
.
Ad esempio, il nome di un metodo ABAP per Pub/Sub è: GET_TOPICS
GET
: l'azione del metodo.TOPICS
: il nome della risorsa.
Un metodo ABAP è costituito dalle seguenti sezioni mappate ai metodi dell'API REST:
Importazione dei parametri
Un metodo API può avere i seguenti parametri di importazione. Questi parametri sono facoltativi e puoi trasmetterli in base ai requisiti di un metodo API che devi utilizzare.
Nome parametro | Tipo | Categoria | Descrizione |
---|---|---|---|
(dal giorno |
String | I parametri di ricerca | I parametri di ricerca vengono aggiunti all'endpoint API dopo ( Sono utilizzate per definire l'ordinamento, l'impaginazione o il filtro. Potrebbero esserci da |
(dal giorno |
String | Parametri del percorso | I parametri del percorso fanno parte dell'endpoint. Vengono usate per puntare a risorse API REST specifiche. Potrebbero esserci da |
(dal giorno |
TY_CODE (Tipo di corso) |
Parametri struttura di input | I dati passati come corpo della richiesta possono essere mappati utilizzando la struttura di input. L'API REST accetta il payload JSON come corpo della richiesta. Il parametro è un parametro completamente digitato che viene convertito in payload JSON per la classe API e allo sviluppatore non è richiesto di lavorare con JSON. Puoi fare riferimento ai tipi di classi disponibili per comprendere i tipi di ABAP per la mappatura dei dati. Ad esempio,
il tipo Un metodo può avere un massimo di un parametro del corpo della richiesta. Alcuni metodi non hanno un corpo della richiesta. |
Esportazione dei parametri
Un metodo API supporta i seguenti parametri di esportazione:
Nome parametro | Tipo | Categoria | Descrizione |
---|---|---|---|
es_raw |
dati | Output non elaborato |
Questo parametro contiene la risposta JSON (Errore o Operazione riuscita) restituita dal metodo API. Mappa questo parametro a una variabile di tipo String per ricevere la stringa di risposta JSON. Nei casi in cui la risposta è di qualsiasi altro tipo, ad esempio xstring per l'output del file in Utilizza questo parametro per scenari di risoluzione avanzata dei problemi o per scenari API avanzati. |
es_output |
TY_CODE (Tipo di corso) | Struttura dell'output |
La risposta JSON viene deserializzata alla struttura ABAP e viene restituita utilizzando questo parametro di esportazione digitato. Puoi utilizzarlo come modo principale per leggere le risposte dell'API utilizzando i costrutti ABAP. |
ev_ret_code |
I (numero intero) | Codice di ritorno |
Il codice restituito che puoi utilizzare per verificare se l'esecuzione del metodo API è riuscita a eseguire correttamente la sua funzionalità. Per maggiori informazioni, consulta Codici restituiti, errori ed eccezioni delle API. |
ev_err_text |
String | Testo dell'errore |
Se la chiamata al metodo non è riuscita, questo parametro contiene il messaggio da utilizzare per conoscere il motivo dell'errore. Per maggiori informazioni, consulta Codici restituiti, errori ed eccezioni delle API. |
ev_err_resp |
|
Risposta di errore |
Il parametro fornisce informazioni aggiuntive sull'errore. Per maggiori informazioni, consulta Codici restituiti, errori ed eccezioni delle API. |
Tipo di classe
Le API Google Cloud utilizzano JSON come formato principale per lo scambio di dati. L'SDK ABAP per Google Cloud fornisce tipi ABAP che vengono mappati allo schema JSON previsto dalle API Google Cloud.
Questi tipi di ABAP e i tipi di tabelle correlate sono disponibili come tipi di classe in ogni classe API fornita dall'SDK.
L'esempio seguente mostra il tipo di classe per la classe dell'API Pub/Sub /GOOG/CL_PUBSUB_V1
.
La descrizione del tipo di classe TY_041
in /GOOG/CL_PUBSUB_V1
è mappata alla risorsa REST, Topic
, che viene passata come payload JSON
al metodo CREATE_TOPICS
.
ABAP Doc
commenti vengono aggiunti a tutte le classi dell'API client.
Quando utilizzi gli strumenti di sviluppo ABAP per SAP NetWeaver (ADT) per lo sviluppo, questi commenti forniscono descrizioni dei tipi di classi.
Codici restituiti dell'API, errori ed eccezioni
Se si verifica un errore quando viene chiamato il metodo API della classe ABAP, l'SDK ABAP per Google Cloud trasmette le informazioni sull'errore al programma chiamante utilizzando i parametri di esportazione dell'SDK o aumentando le eccezioni.
Codice restituito ed errori dell'API
Le API Google Cloud utilizzano un modello di errore che offre un'esperienza coerente su diverse API. Quando un metodo API Google Cloud viene chiamato dall'SDK, i seguenti parametri contengono il codice e i messaggi dell'API di ritorno:
ev_ret_code
: restituisce un codice o un codice di errore nella risposta.ev_error_text
: messaggio di errore nella risposta, se presente.es_raw
: risposta di errore non elaborata, se una chiamata al metodo API non è andata a buon fine.
Per controllare lo stato di una chiamata API, utilizza il metodo IS_SUCCESS
. Puoi utilizzare il
valore ev_ret_code
per determinare se una chiamata API
è riuscita o meno. In generale, quando ev_ret_code = 2XX
, la chiamata al metodo viene considerata riuscita. Per tutti gli altri valori, la chiamata al metodo viene considerata non riuscita.
IF lo_client->is_success( ev_ret_code ).
"Success: Implement custom code
ELSE
"Handle the HTTP error status code
ENDIF.
Per alcune API Google Maps Platform, se chiami un'API con input non validi, l'API restituisce un codice di stato HTTP riuscito 2XX
con un messaggio e uno stato di errore, anziché un codice di stato di errore HTTP (4XX
o 5XX
). Questo messaggio e lo stato di errore nella risposta dell'API possono aiutarti a risolvere il problema e a correggere gli input non validi.
Per queste API Google Maps Platform, oltre al
codice restituito ev_ret_code
, controlla il messaggio e lo stato dell'errore
restituiti nella risposta dell'API chiamando il metodo IS_STATUS_OK
dopo
la chiamata API. Lo snippet seguente mostra un esempio di come puoi utilizzare il metodo IS_STATUS_OK
:
IF lo_client->is_status_ok( ).
"Success: Implement custom code
ELSE
"Handle the HTTP error status code
ENDIF.
Il parametro es_err_resp
fornisce informazioni aggiuntive sull'errore.
La seguente tabella illustra i campi del parametro es_err_resp
.
Campo | Valore |
---|---|
es_err_resp-error_description |
Messaggio di errore ricevuto dall'API. Questo valore è uguale al parametro ev_error_text . |
es_err_resp-error |
Descrizione dello stato HTTP restituita dal client HTTP SAP. |
Gestire gli errori restituiti dalle API Google Cloud
Utilizza le seguenti indicazioni per gestire gli errori restituiti dalle API di Google Cloud:
Codici di errore comuni:per informazioni sugli errori comuni restituiti dalle API di Google Cloud e sulla loro causa, consulta la pagina relativa ai codici di errore.
Acquisisci informazioni dettagliate sugli errori: per acquisire informazioni dettagliate sugli errori con l'SDK ABAP per Google Cloud, utilizza il parametro di esportazione
es_raw
dai metodi della classe SDK e mappa questo parametro a una variabile di tipoString
. Questa variabile contiene una risposta JSON contenente messaggi di errore dettagliati e violazioni specifiche riscontrate dalle API.Visualizza errore dettagliato: per visualizzare informazioni dettagliate sull'errore, utilizza uno dei seguenti metodi:
- Debugger: visualizza i contenuti della variabile che contiene la risposta JSON nello strumento di debug ABAP per ulteriori analisi.
SAP GUI: utilizza la classe ABAP
cl_demo_output=>display( lv_response )
per una rappresentazione visiva dell'errore all'interno di un programma di report. Se utilizzi i metodi dell'API in un programma di report e l'esecuzione del programma è in modalità in primo piano, utilizza la classe ABAPcl_demo_output=>display_json( lv_response )
.Il seguente snippet di codice illustra come visualizzare la risposta dell'API in caso di errore:
DATA lv_response TYPE string, TRY. lo_translate = NEW #( iv_key_name = 'DEMO_TRANSLATE' ). lo_translate->translate_translations EXPORTING is_input = ls_input IMPORTING es_raw = lv_response es_output = ls_output ev_ret_code = lv_ret_code ev_err_text = lv_err_text es_err_resp = ls_err_resp. IF lo_translate->is_error( lv_ret_code ) = abap_true. " Display API response in case of an error cl_demo_output=>display_json( lv_response ). ENDIF. CATCH /goog/cx_sdk INTO lo_exception. lv_err_text = lo_exception->get_text( ). ENDTRY.
Documentazione specifica delle API: alcune API Google Cloud forniscono informazioni dettagliate sugli errori e indicazioni per la risoluzione dei problemi nella relativa documentazione individuale. Per risolvere un errore relativo a un'API, consulta la documentazione specifica per l'API, ad esempio Pub/Sub, Document AI e Cloud Storage.
Eccezioni
Quando si verifica un errore imprevisto durante una chiamata al metodo API, ad esempio una configurazione errata dell'SDK o un errore di comunicazione HTTP, l'SDK genera un'eccezione di classe di tipo /GOOG/CX_SDK
. Devi individuare questa eccezione nel codice e scrivere una logica di gestione degli errori appropriata.
Puoi visualizzare il messaggio di errore chiamando il metodo get_text
della classe
d'eccezione. Il messaggio di errore restituito dalla classe di eccezione ha il seguente formato:
/GOOG/MSG : Return_Code - Error_Message
La causa dell'errore e dei passaggi di risoluzione dipende dal valore di Return_Code
.
Valore di Return_Code |
Causa dell'errore | Risoluzione |
---|---|---|
461 |
L'SDK ABAP per Google Cloud utilizza un codice di reso speciale, 461 , per
informare che un passaggio specifico di installazione e configurazione non viene eseguito
o completato in modo errato. Il valore Error_Message corrispondente fornisce
ulteriori dettagli sull'errore. |
Devi leggere attentamente le istruzioni di installazione e configurazione dell'SDK e assicurarti che vengano eseguite correttamente. |
Qualsiasi altro valore | Questo codice restituito è l'ultimo errore HTTP della classe client HTTP standard di SAP. Questo errore indica che SAP ICM ha riscontrato un problema di comunicazione durante la chiamata a un metodo dell'API REST Google. | Devi esaminare attentamente le impostazioni di rete, firewall e SAP ICM e assicurarti che le configurazioni consentano le chiamate HTTP alle API Google Cloud. |
Per i messaggi di errore tipici attivati nell'SDK ABAP per Google Cloud e la relativa risoluzione, consulta la guida alla risoluzione dei problemi.
Logging
La versione SAP BTP dell'SDK ABAP per Google Cloud consente di registrare i messaggi di errore utilizzando un framework di logging incorporato. L'oggetto log /GOOG/LOG_OBJECT
e l'oggetto secondario /GOOG/LOG_SUBOBJECT
vengono forniti con l'SDK che puoi utilizzare per creare la configurazione predefinita dei log. Per ulteriori informazioni sulla creazione
della configurazione predefinita dei log, consulta Configurare il logging.
Puoi visualizzare i log delle applicazioni utilizzando l'app Google SDK:Application Logs Display. Per ulteriori informazioni, consulta Visualizzare i log.
Mappatura dei tipi di dati
La seguente tabella fornisce un elenco completo dei valori type
e format
supportati dal servizio di rilevamento delle API di Google e dal tipo di dati
ABAP corrispondente.
Per saperne di più sui valori type
e format
supportati dal servizio di rilevamento delle API di Google, consulta Riepilogo di tipi e formati.
Digita valore | Valore formato | Tipo di dati ABAP | Significato |
---|---|---|---|
tutte | DIGITA RIF. AI DATI | La proprietà può essere di qualsiasi tipo. Definito dalla specifica dello schema JSON. | |
array | TIPO DI TABELLA CON CHIAVE NON UNICHE | Un array di valori JavaScript. La proprietà items indica lo schema per i valori dell'array. Definito dalla specifica dello schema JSON. | |
boolean | ABAP_BOOLEAN | Un valore booleano, può essere "true" o "false". Definito dalla specifica dello schema JSON. | |
integer | int32 | INT4 | Un numero intero a 32 bit con segno. Ha un valore minimo di -2.147.483.648 e un valore massimo di 2.147.483.647 (incluso). |
integer | uint32 | INT4 | Un numero intero senza segno a 32 bit. Ha un valore minimo di 0 e un valore massimo di 4.294.967.295 (incluso). |
number | double | /GOOG/NUM_DOUBLE (stringa) |
rappresentazione in virgola mobile IEEE 754 a 64 bit a precisione doppia. |
number | float | /GOOG/NUM_FLOAT (stringa) |
rappresentazione in virgola mobile IEEE 754 a 32 bit a precisione singola. |
oggetto | TIPI | Un oggetto JavaScript. Definito dalla specifica dello schema JSON. | |
string | STRING | Una stringa arbitraria. Definito dalla specifica dello schema JSON. | |
string | byte | STRING | Una stringa riempita di byte con codifica Base64, codificata con un URL e un nome file alfabeto sicuro (a volte indicata come "sicura per il web" o "base64url"). Definito da RFC 4648. |
string | date | STRING | Una data RFC 3339 nel formato AAAA-MM-GG. Definito nella specifica dello schema JSON. |
string | data-ora | STRING | Un timestamp RFC 3339 nel fuso orario UTC. Nel formato aaaa-MM-ggTHH:mm:ss.SSSZ. La parte in millisecondi (".SSS") è facoltativa. Definito nella specifica dello schema JSON. |
string | google-datetime | STRING | Un timestamp RFC 3339 nel fuso orario UTC. Nel formato aaaa-MM-ggTHH:mm:ss.SSSZ. La parte in millisecondi (".SSS") è facoltativa. |
string | durata-google | STRING | Una stringa termina con il suffisso "s" (che indica i secondi) ed è preceduta dal numero di secondi, con i nanosecondi espressi come secondi frazionari. Il punto viene sempre utilizzato come punto decimale, non come virgola. |
string | maschera-google-field | STRING | Una stringa in cui i nomi dei campi sono separati da una virgola. I nomi dei campi sono rappresentati secondo convenzioni di denominazione con cammello inferiore. |
string | int64 | STRING | Un numero intero a 64 bit con segno. Ha un valore minimo di -9.223.372.036.854.775.808 e un valore massimo di 9.223.372.036.854.775.807 (inclusi). |
string | uint64 | STRING | Un numero intero senza segno a 64 bit. Ha un valore minimo di 0 e un valore massimo di (2^64)-1 (incluso). |
Serializzazione e deserializzazione della richiesta e della risposta API
Per impostazione predefinita, la versione SAP BTP dell'SDK ABAP per Google Cloud si occupa del marshalling e dell'annullamento del marshalling delle richieste e delle risposte API. Ogni classe ABAP per un'API Google Cloud ha tipi ABAP incorporati per formare l'input e l'output dei metodi. Per implementare la trasformazione personalizzata di richiesta e risposta, puoi utilizzare l'area di miglioramento con le definizioni di SAP Business Add In (BAdI) fornite con l'SDK.
Implementare la trasformazione personalizzata
L'area di miglioramento /GOOG/ES_TRANSFORM_JSON
, fornita con l'SDK,
include le seguenti definizioni BAdI:
/GOOG/BADI_SERIALIZE_JSON
: per implementare una logica di serializzazione personalizzata./GOOG/BADI_DESERIALIZE_JSON
: per implementare una logica di deserializzazione personalizzata.
Puoi scrivere logica di trasformazione specifica nelle implementazioni di questi BAdI.
Le interfacce di questi BAdI hanno IV_METHOD_NAME
come parametro di importazione.
Utilizzerai questo parametro per isolare la logica di trasformazione per ogni API e metodo API utilizzando i blocchi IF….ENDIF
. Nel blocco di implementazione, imposta il parametro di esportazione EV_HANDLED
su X
.
Per implementare la trasformazione personalizzata:
Per
/GOOG/BADI_SERIALIZE_JSON
, crea un'implementazione di miglioramento:- Per trasformare le richieste API, crea un'implementazione per
/GOOG/BADI_SERIALIZE_JSON
BAdI con una classe di implementazione. - Per trasformare le risposte dell'API, crea un'implementazione per
/GOOG/BADI_DESERIALIZE_JSON
BAdI con una classe di implementazione.
- Per trasformare le richieste API, crea un'implementazione per
Determina l'ID del metodo API per il quale devi scrivere la trasformazione. L'ID del metodo è la concatenazione di quanto segue:
- Il valore della costante dell'attributo classe
C_SERVICE_NAME
. - Il carattere
#
. - La descrizione del metodo della classe API per il quale è necessario implementare la trasformazione.
Ad esempio, per scrivere trasformazioni per la pubblicazione di messaggi in un argomento Pub/Sub, l'ID del metodo è:
pubsub:v1#pubsub.projects.topics.publish
- Il valore della costante dell'attributo classe
Nell'implementazione del metodo del BAdI:
- Per l'ID metodo, scrivi la trasformazione personalizzata in un
IF….ENDIF block
. Imposta il parametro di esportazione
EV_HANDLED
suX
.Se il criterio
EV_HANDLED
non viene impostato suX
, viene applicata la logica predefinita di marshalling e annullamento del marshalling dell'SDK.
- Per l'ID metodo, scrivi la trasformazione personalizzata in un
Contrassegna l'elemento
API State
del corso di implementazione comeUse System-Internally (Contract C1)
. La logica di trasformazione personalizzata viene richiamata durante il runtime. La logica di serializzazione e deserializzazione predefinita fornita con l'SDK verrà ignorata.
Spazio dei nomi
Tutto il codice fornito da Google viene inserito nello spazio dei nomi riservato /GOOG/
.
Richiedi assistenza
Se hai bisogno di aiuto per risolvere i problemi con l'SDK ABAP per Google Cloud, procedi nel seguente modo:
Consulta la guida alla risoluzione dei problemi relativi all'SDK ABAP per Google Cloud.
Poni le tue domande e discuti dell'SDK ABAP per Google Cloud con la community dei forum di Cloud.
Raccogli tutte le informazioni di diagnostica disponibili e contatta l'assistenza clienti Google Cloud. Per informazioni su come contattare l'assistenza clienti, vedi Ottenere assistenza per SAP su Google Cloud.