Sviluppo di applicazioni con la versione on-premise o qualsiasi versione cloud di ABAP SDK for Google Cloud

Questo documento fornisce informazioni e risorse utili per aiutarti a sviluppare applicazioni SAP utilizzando la versione on-premise o qualsiasi versione cloud dell'SDK ABAP per Google Cloud.

Questo documento è rivolto agli sviluppatori SAP ABAP.

Per un elenco completo delle librerie client fornite dall'edizione on-premise o di qualsiasi cloud di ABAP SDK for Google Cloud, consulta Librerie client dell'edizione on-premise o di qualsiasi cloud di ABAP SDK for Google Cloud.

Interazione con una sola finestra

Ogni API Google Cloud abilitata nell'ABAP SDK 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 dell'API Google Cloud. Ogni metodo pubblico è inoltre costituito da parametri IMPORTING e parametri 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 corrispondente classe ABAP funge da unico punto di interazione. Chiamiamo questo concetto Interazione singola finestra, che protegge da tutte le complessità sottostanti dell'interazione con un' API Google Cloud e presenta un'interfaccia semplificata. Questa interfaccia semplificata consente di concentrarsi sulle soluzioni aziendali in fase di sviluppo utilizzando l'SDK, senza preoccuparsi delle funzionalità dell'SDK sottostante.

Flusso di interazione

Per chiamare un metodo dell'API, hai il seguente flusso di interazione:

1. Connettiti a un'API.
2. Crea una richiesta di input utilizzando i tipi ABAP.
3. Chiama un metodo dell'API.
4. Analizza gli errori e le eccezioni.
5. Leggi la risposta utilizzando i tipi ABAP.

Stub del client API

Una tipica classe stub client dell'API è costituita dalle seguenti sezioni:

• I tipi ABAP che mappano agli schemi dell'API. Utilizzi i tipi ABAP per creare una richiesta di input e analizzare la risposta.
• Le costanti e gli attributi per l'utilizzo interno o esterno.
• I metodi dell'API per interagire con le risorse dell'API.

Funzionalità

Le funzionalità dell'ABAP SDK per Google Cloud sono:

• Comunicazione HTTP: l'SDK stabilisce la connessione HTTP con gli endpoint API.
• Marshaling delle richieste: l'SDK converte i dati nei tipi ABAP in un payload JSON che viene inviato come corpo della richiesta.
• Gestione di errori ed eccezioni: l'SDK gestisce i codici di ritorno e i messaggi di errore retitrati dall'API e genera eventuali eccezioni.
• Unmarshalling della risposta: l'SDK reconverte il payload JSON nel corpo della risposta nei tipi ABAP corrispondenti.
• Registrazione degli errori locali: l'SDK registra i messaggi di errore utilizzando il framework di logging.

Progettazione dell'API ed Explorer API

Le API pubblicate da Google seguono un design orientato alle risorse. Per saperne di più sul design delle API di Google, consulta la guida alla progettazione delle API.

L'ABAP SDK per Google Cloud consente l'integrazione con le API basate su REST pubblicate da Google.

Explorer API è uno strumento che consente di provare i metodi dell'API Google Cloud senza scrivere codice. Utilizza questo strumento per studiare le API e i parametri di input obbligatori che vuoi passare ai metodi ABAP corrispondenti.

Costruzioni di codice

Spiega i costrutti di codice che utilizzi per creare i programmi ABAP utilizzando l'ABAP SDK per Google Cloud.

Costruttore

Per prima cosa, devi creare un'istanza della classe API che vuoi utilizzare. Il costruttore di ogni classe API avrà uno schema 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

Parametri di importazione

La tabella seguente illustra i parametri di importazione di un costruttore di metodi:

Metodo API

Con la progettazione delle API Google Cloud orientata alle risorse, un metodo dell'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 recuperare la configurazione di un argomento.

Per mappare un metodo di classe ABAP a un metodo dell'API, puoi fare riferimento alla descrizione del metodo che segue il pattern:<resource>.<method_verb>.

Ad esempio, la descrizione del metodo per 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 il pattern:<method_verb>_<resource>.

Ad esempio, un nome di metodo ABAP per Pub/Sub è: GET_TOPICS

• GET: l'azione del metodo.
• TOPICS: il nome della risorsa.

Un metodo ABAP è costituito dalle seguenti sezioni che mappano ai metodi dell'API REST:

Parametri di importazione

Un metodo API può avere i seguenti parametri di importazione. Questi parametri sono facoltativi e puoi passarli in base ai requisiti di un metodo dell'API che devi utilizzare.

Parametri di esportazione

Un metodo API supporta i seguenti parametri di esportazione:

Tipo di corso

Le API Google Cloud utilizzano JSON come formato principale per lo scambio di dati. L'ABAP SDK per Google Cloud fornisce tipi ABAP che mappano allo schema JSON previsto dalle API Google Cloud.

Questi tipi ABAP e i tipi di tabelle correlati sono disponibili come tipi di classe in ogni classe API fornita dall'SDK.

L'esempio seguente mostra il tipo di classe per la classe /GOOG/CL_PUBSUB_V1 dell'API Pub/Sub.

La descrizione del tipo di classe TY_041 in /GOOG/CL_PUBSUB_V1 si mappa alla risorsa REST Topic, che viene passata come payload JSON al metodo CREATE_TOPICS.

I commenti ABAP Doc vengono aggiunti a tutti i classi dell'API client. Quando utilizzi ABAP Development Tools per SAP NetWeaver (ADT) per lo sviluppo, questi commenti forniscono descrizioni dei tipi di classi.

Codici di ritorno, errori ed eccezioni dell'API

Se si verifica un errore durante la chiamata del 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 sollevando eccezioni.

Codice di ritorno e errori dell'API

Le API Google Cloud utilizzano un modello di errore che offre un'esperienza uniforme tra le diverse API. Quando un metodo dell'API Google Cloud viene chiamato dall'SDK, i seguenti parametri contengono il codice di ritorno e i messaggi dell'API:

• ev_ret_code: codice di ritorno o 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 è riuscita.

Per controllare lo stato di una chiamata all'API, utilizza il metodo IS_SUCCESS. Puoi utilizzare il valore di ev_ret_code per determinare se una chiamata API è andata a buon fine o meno. In genere, quando ev_ret_code = 2XX, la chiamata al metodo è 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 di Google Maps Platform, se chiami un'API con input non validi, l'API restituisce un codice di stato di esito positivo HTTP 2XX con un messaggio di errore e uno stato di errore, anziché un codice di stato di errore HTTP (4XX o 5XX). Questo messaggio di errore e questo stato di errore nella risposta dell'API possono aiutarti a risolvere il problema e correggere gli input non validi.

Per queste API di Google Maps Platform, oltre al codice di ritorno ev_ret_code, controlla il messaggio di errore e lo stato di errore restituito nella risposta dell'API chiamando il metodo IS_STATUS_OK dopo la chiamata dell'API. Lo snippet seguente mostra un esempio di come 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 ulteriori informazioni sull'errore. La tabella seguente illustra i campi del parametro es_err_resp.

Gestire gli errori restituiti dalle API Google Cloud

Segui le indicazioni riportate di seguito per gestire gli errori restituiti dalle API Google Cloud:

• Codici di errore comuni:per informazioni sugli errori comuni restituiti dalle API Google Cloud e sulla relativa causa, consulta i codici di errore.

• Acquisisci un errore dettagliato: 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 tipo String. Questa variabile contiene una risposta JSON contenente messaggi di errore dettagliati e violazioni specifiche riscontrate dalle API.

• Visualizza l'errore dettagliato:per visualizzare informazioni dettagliate sull'errore, utilizza uno dei seguenti metodi:

  • Debug: visualizza i contenuti della variabile che contiene la risposta JSON nello strumento di debug ABAP per un'ulteriore analisi.

  • Interfaccia utente SAP: utilizza la classe ABAP cl_demo_output=>display( lv_response ) per la 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à primo piano, utilizza la classe ABAP cl_demo_output=>display_json( lv_response ).

    Il seguente snippet di codice mostra 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 dell'API:alcune API Google Cloud forniscono informazioni dettagliate sugli errori e indicazioni per la risoluzione dei problemi nella relativa documentazione. Per risolvere un errore relativo a un'API, consulta la documentazione specifica dell'API, ad esempio Pub/Sub, Document AI e Cloud Storage.

Eccezioni

Quando si verifica un errore imprevisto durante una chiamata al metodo dell'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 intercettare questa eccezione nel codice e scrivere una logica di gestione degli errori appropriata.

Puoi ottenere il messaggio di errore chiamando il metodo get_text della classe dell'eccezione. Il messaggio di errore restituito dalla classe eccezione ha il seguente formato:

/GOOG/MSG : Return_Code - Error_Message

La causa dell'errore e i passaggi per la risoluzione dipendono dal valore di Return_Code.

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

L'SDK ABAP per Google Cloud ti consente di registrare i messaggi di errore utilizzando un framework di logging incorporato. L'oggetto log ZGOOG e l'oggetto secondario ZABAP_SDK vengono forniti con i file di trasporto dell'SDK che puoi utilizzare come oggetti predefiniti per le configurazioni dei log.

In qualità di sviluppatore, puoi passare i tuoi oggetti e sottooggetti di log personalizzati durante l'inizializzazione dello stub del client API. È necessaria una configurazione aggiuntiva per indicare all'SDK di utilizzare gli oggetti log personalizzati anziché l'oggetto e il sottooggetto log predefiniti.

L'esempio seguente mostra un codice di chiamata con oggetto e sottooggetto log personalizzati tramessi:

TRY.
    CREATE OBJECT lo_api_class
      EXPORTING
        iv_key_name   = 'CLIENT_KEY'
        iv_log_obj    = 'ZSD'            "Application Log Object
        iv_log_subobj = 'ZSD_SALES_ORDERS'. "Subobject
  CATCH /goog/cx_sdk INTO DATA(lo_exception).
      DATA(lv_msg) = lo_exception->get_text( ).
      MESSAGE lv_msg TYPE 'E'.
ENDTRY.

Per ulteriori informazioni sulla configurazione della registrazione e sulla creazione di oggetti log personalizzati, consulta Registrazione delle applicazioni.

Mappatura dei tipi di dati

Le tabelle seguenti forniscono un elenco completo dei valori type e format supportati dal servizio di rilevamento delle API di Google e il corrispondente tipo di dati ABAP.

Per ulteriori informazioni sui valori type e format supportati dal servizio di rilevamento delle API di Google, consulta Riepilogo di tipi e formati.

Programmi demo

L'ABAP SDK for Google Cloud include diversi programmi di dimostrazione che mostrano come utilizzare i servizi Google con l'SDK. I programmi di dimostrazione si trovano nel pacchetto /GOOG/DEMO.

I programmi di dimostrazione coprono una serie di servizi Google, ad esempio:

• Document AI
• Pub/Sub
• Cloud Translation
• Cloud Storage
• Secret Manager

I programmi di dimostrazione sono un ottimo modo per imparare a utilizzare l'ABAP SDK per Google Cloud. Sono anche un ottimo modo per testare la configurazione. La documentazione del programma con le demo fornisce ulteriori dettagli su ogni demo.

Per accedere ai programmi demo, segui questi passaggi:

1. In SAP GUI, esegui il codice transazione /GOOG/SDK_IMG.

   In alternativa, esegui il codice transazione SPRO e poi fai clic su Immagine di riferimento SAP.

2. Vai ad ABAP SDK for Google Cloud > Demo.

Serializzazione e deserializzazione della richiesta e della risposta dell'API

Per impostazione predefinita, l'SDK ABAP per Google Cloud si occupa del marshalling e dello unmarshalling delle richieste e delle risposte dell'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 il punto di miglioramento con le definizioni di componenti aggiuntivi per le aziende (BAdI) SAP fornite con l'SDK.

Implementare una trasformazione personalizzata

Lo spot di miglioramento /GOOG/ES_TRANSFORM_JSON, fornito con l'SDK, include le seguenti definizioni BAdI:

• /GOOG/BADI_SERIALIZE_JSON: per implementare la logica di serializzazione personalizzata.
• /GOOG/BADI_DESERIALIZE_JSON: per implementare la logica di deserializzazione personalizzata.

Puoi scrivere una logica di trasformazione specifica nelle implementazioni di questi BAdI. Le interfacce di questi BAdI hanno IV_METHOD_NAME come parametro di importazione. Utilizza questo parametro per separare 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:

1. Per /GOOG/BADI_SERIALIZE_JSON, crea un'implementazione del miglioramento:

   • Per trasformare le richieste API, crea un'implementazione per BAdI /GOOG/BADI_SERIALIZE_JSON con una classe di implementazione.
   • Per trasformare le risposte dell'API, crea un'implementazione per BAdI /GOOG/BADI_DESERIALIZE_JSON con una classe di implementazione.

2. Determina l'ID metodo del metodo dell'API per cui devi scrivere la trasformazione. L'ID metodo è la concatenazione di quanto segue:

   • Il valore della costante dell'attributo della classe C_SERVICE_NAME.
   • Il carattere #.
   • La descrizione del metodo della classe dell'API per cui devi implementare la trasformazione.

   Ad esempio, per scrivere trasformazioni per la pubblicazione di messaggi in un argomento Pub/Sub, l'ID metodo è: pubsub:v1#pubsub.projects.topics.publish

3. Nell'implementazione del metodo del BAdI, svolgi i seguenti passaggi:

   1. Per l'ID metodo, scrivi la trasformazione personalizzata sotto un IF….ENDIF block.

   2. Imposta il parametro di esportazione EV_HANDLED su X.

      Se EV_HANDLED non è impostato su X, viene applicata la logica di marshalling e unmarshalling predefinita dell'SDK.

La logica di trasformazione personalizzata viene invocata durante l'esecuzione. Quando utilizzi le trasformazioni personalizzate, la logica di serializzazione e deserializzazione predefinita fornita con l'SDK viene saltata.

Spazio dei nomi

Tutto il codice fornito da Google viene inserito nello spazio dei nomi riservato /GOOG/.

Assistente per la programmazione

La procedura guidata di codice ti aiuta ad accelerare lo sviluppo di tutti i metodi pubblici degli stub client dell'API forniti dall'ABAP SDK per Google Cloud. La procedura guidata di codice è simile all'opzione pattern utilizzata nello sviluppo ABAP. Tuttavia, oltre all'ABAP pattern, la procedura guidata di codice è utile anche per:

• Genera tutte le dichiarazioni dei dati richieste.
• Fornisce segnaposto nel codice per i parametri di importazione del metodo di registrazione.
• Genera una risposta di base e gestisce le eccezioni.
• Fornisce personalizzazioni e funzionalità aggiuntive sotto forma di scelta della sintassi ABAP 7.5, aggiunta e rimozione di blocchi per l'apertura e la chiusura delle connessioni HTTP.
• Fornisce un'opzione di copia per il codice generato.

La procedura guidata per il codice fornisce solo un frame di codice che puoi modificare in base alle tue esigenze. La procedura guidata di codice supporta la sintassi di SAP S/4HANA e SAP ECC.

Per accedere alla procedura guidata di codice:

1. In SAP GUI, esegui il codice transazione /GOOG/SDK_IMG.

   In alternativa, esegui il codice transazione SPRO e poi fai clic su Immagine di riferimento SAP.

2. Vai ad ABAP SDK for Google Cloud > Utilità > Assistente codice.

L'esempio seguente mostra il codice boilerplate creato per un metodo API CREATE_TOPICS dello stub client Pub/Sub, /GOOG/CL_PUBSUB_V1:

 DATA:
   lv_p_projects_id TYPE string,
   lv_p_topics_id   TYPE string,
   ls_input         TYPE /goog/cl_pubsub_v1=>ty_041.

 TRY.

* Open HTTP Connection
     DATA(lo_client) = NEW /goog/cl_pubsub_v1( iv_key_name = 'client_key' ).

* Populate relevant parameters
* lv_p_projects_id = 'string_value'.
* lv_p_topics_id = 'string_value'.
* ls_input = .

* Call API method
     CALL METHOD lo_client->create_topics
       EXPORTING
         iv_p_projects_id = lv_p_projects_id
         iv_p_topics_id   = lv_p_topics_id
         is_input         = ls_input
       IMPORTING
*        es_raw           =
         es_output        = DATA(ls_output)
         ev_ret_code      = DATA(lv_ret_code)
         ev_err_text      = DATA(lv_err_text)
         es_err_resp      = DATA(ls_err_resp).

     IF /goog/cl_http_client=>is_success( lv_ret_code ).
       MESSAGE 'Success' TYPE 'S'.
     ELSE.
       MESSAGE lv_err_text TYPE 'E'.
     ENDIF.

* Close HTTP Connection
     lo_client->close( ).

   CATCH /goog/cx_sdk INTO DATA(lo_exception).
     MESSAGE lo_exception->get_text( ) TYPE 'E'.
 ENDTRY.

Architetture di riferimento

Esplora l'SDK ABAP per Google Cloud con l'aiuto delle architetture di riferimento e scopri come l'SDK può portare innovazione al tuo panorama di applicazioni SAP. Puoi utilizzare l'SDK per eseguire l'integrazione con Vertex AI per funzionalità di AI e machine learning avanzate e con altri servizi Google Cloud come BigQuery, Pub/Sub, Cloud Storage e molti altri ancora. Per ulteriori informazioni, consulta le Architetture di riferimento per l'ABAP SDK per Google Cloud.

Assistenza

Se hai bisogno di aiuto per risolvere i problemi relativi all'SDK ABAP per Google Cloud, segui questi passaggi:

• Fai riferimento alla guida alla risoluzione dei problemi di ABAP SDK for Google Cloud.

• Poni le tue domande e discuti dell'ABAP SDK per Google Cloud con la community nei forum di Cloud.

• Raccogli tutte le informazioni di diagnostica disponibili e contatta l'assistenza clienti Google Cloud. Per informazioni su come contattare il team dell'assistenza clienti, consulta Assistenza per SAP su Google Cloud.