Desenvolvimento de aplicativos com a edição SAP BTP do SDK ABAP para Google Cloud

Neste documento, você encontra informações e recursos úteis para desenvolver aplicativos SAP usando a edição SAP BTP do SDK do ABAP para Google Cloud.

Este documento é destinado a desenvolvedores do SAP ABAP.

Para conferir uma lista completa de bibliotecas de cliente que a edição SAP BTP do SDK do ABAP para Google Cloud oferece, consulte SDK ABAP para bibliotecas de cliente do Google Cloud.

Janela única de interação

Cada API do Google Cloud ativada no ABAP SDK for Google Cloud é representada por uma classe ABAP, contida no pacote /GOOG/CLIENT. Uma classe ABAP consiste em vários métodos públicos e cada um deles corresponde a um método da Google Cloud API. Cada método público consiste ainda mais nos parâmetros IMPORTING e EXPORTING. Uma classe ABAP também contém tipos de dados personalizados, que podem ser usados para construir e mapear os parâmetros IMPORTING e EXPORTING. Esses tipos de dados personalizados são mapeados para as definições de esquema da API.

Para cada interação com uma API do Google Cloud de destino, a classe ABAP correspondente atua como o único ponto de interação. Chamamos esse conceito de única janela de interação, que protege todas as complexidades subjacentes da interação com uma API do Google Cloud e apresenta uma interface simplificada. Essa interface simplificada permite que você se concentre nas soluções empresariais que estão sendo desenvolvidas usando o SDK, sem se preocupar com os recursos subjacentes do SDK.

Janela única de interação

Fluxo de interação

Para chamar um método de API, você tem o seguinte fluxo de interação:

Conecte-se a uma API.
Crie uma solicitação de entrada usando os tipos ABAP.
Chame um método de API.
Analise erros e exceções.
Leia a resposta usando os tipos ABAP.

Interação do desenvolvedor

Stub de cliente da API

Uma classe de stubs de cliente de API típica consiste nas seguintes seções:

Os tipos ABAP que mapeiam para os esquemas da API. Use tipos ABAP para criar uma solicitação de entrada e analisar a resposta.
As constantes e os atributos para uso interno ou externo.
Os métodos de API para interagir com os recursos da API.

Estrutura da classe

Recursos

O SDK ABAP para Google Cloud inclui os seguintes recursos:

Comunicação HTTP: o SDK estabelece uma conexão HTTP com os endpoints da API.
Solicitação do marshaling: o SDK converte dados em tipos ABAP para payload JSON que é enviado como o corpo da solicitação.
Tratamento de erros e exceções: o SDK processa os códigos e as mensagens de erro retornados pela API e gera exceções, se houver.
Resposta desmarcada: o SDK converte de volta o payload JSON no corpo da resposta para os tipos ABAP correspondentes.
Geração de registros de erros locais: o SDK registra as mensagens de erro usando o framework logging.

Design de APIs e APIs Explorer do Google

As APIs publicadas pelo Google seguem o design orientado a recursos. Para saber mais sobre o design de API do Google, consulte o guia de design de API.

O ABAP SDK for Google Cloud permite a integração com as APIs baseadas em REST publicadas pelo Google.

A API Explorer do Google é uma ferramenta que permite testar métodos da API Google Cloud sem escrever código. Use essa ferramenta para estudar as APIs e os parâmetros de entrada necessários que você quer passar para os métodos ABAP correspondentes.

Construção de códigos

Explica as construções de código que você usa para criar seus programas do ABAP usando o ABAP SDK for Google Cloud.

Construtor

Primeiro, você instancia a classe de API que você quer usar. O construtor de cada classe de API teria um padrão semelhante ao mostrado no exemplo a seguir:

    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

Como importar parâmetros

A tabela a seguir explica os parâmetros de importação de um construtor de método:

Nome do parâmetro	Tipo	Obrigatório/Opcional	Descrição
`iv_key_name`	`/GOOG/KEYNAME`	Obrigatório	Especifique a chave do cliente da configuração que você usa para criar uma conexão com o Google Cloud. Para informações sobre a configuração da chave do cliente, consulte Autenticação.
`iv_log_object`	`balobj_d`	Opcional	Especifique o objeto de registro do aplicativo, que você usa para armazenar os erros gerados pelo SDK. Para informações sobre a configuração da geração de registros, consulte Geração de registros do aplicativo.
`iv_log_subobject`	`balsubobj`	Opcional	Especifique o subobjeto de registro do aplicativo, que você usa para armazenar os erros gerados pelo SDK. Para informações sobre a configuração da geração de registros, consulte Geração de registros do aplicativo.

Método de API

Com o design orientado a recursos das APIs do Google Cloud, um método de API é uma ação que pode ser executada em um recurso publicado pela API.

Por exemplo, se Topics for um recurso publicado pela API Pub/Sub, topics.get será um método de API que representa uma ação no recurso Topics para receber a configuração de um tópico.

Para mapear um método de classe ABAP para um método de API, consulte a descrição do método que segue o padrão:<resource>.<method_verb>.

Por exemplo, a descrição de um método do Pub/Sub é pubsub.projects.topics.get.

projects.topics: o nome do recurso.
get: a ação do método.

Descrição do método interface do SAP

O nome em um mapeamento de método ABAP para uma ação da API segue o padrão:<method_verb>_<resource>.

Por exemplo, um nome de método ABAP para Pub/Sub é: GET_TOPICS

GET: a ação do método.
TOPICS: o nome do recurso.

Um método ABAP consiste nas seguintes seções que mapeiam para os métodos da REST API:

Nome do método

Como importar parâmetros

Um método de API pode ter os parâmetros de importação a seguir. Esses parâmetros são opcionais e podem ser passados com base nos requisitos de um método de API que você precisa usar.

Nome do parâmetro Tipo Categoria Descrição

Nome do parâmetro	Tipo	Categoria	Descrição
`iv_q_NAME` (De `0` até `n`)	String	Parâmetros de consulta	Os parâmetros de consulta são anexados ao endpoint da API depois de (`?`). Eles são usados para definir classificação, paginação ou filtro. Pode haver parâmetros de consulta de `0` a `n`.
`iv_p_NAME` (De `0` até `n`)	String	Parâmetros de caminho	Os parâmetros de caminho fazem parte do endpoint. Eles são usados para apontar para recursos específicos da REST API. Pode haver parâmetros de caminho de `0` a `n`.
`is_input` (De `0` até `1`)	TY_`CODE` (tipo de classe)	Parâmetros de estrutura de entrada	Os dados transmitidos como o corpo da solicitação podem ser mapeados usando a estrutura de entrada. A API REST aceita o payload JSON como o corpo da solicitação. É um parâmetro totalmente digitado que é convertido em payload JSON para a classe de API e o desenvolvedor não precisa trabalhar com JSON. Consulte os tipos de classe disponíveis para entender os tipos de ABAP para o mapeamento de dados. Por exemplo, o tipo `/GOOG/CL_PUBSUB_V1=>TY_041` é mapeado para o recurso REST: Topic, que é transmitido como payload do JSON para o método `CREATE_TOPICS`. Um método pode ter no máximo um parâmetro de corpo de solicitação. Alguns métodos não têm um corpo de solicitação.

iv_q_NAME

(De 0 até n)

String

Parâmetros de consulta

Os parâmetros de consulta são anexados ao endpoint da API depois de (?).

Eles são usados para definir classificação, paginação ou filtro.

Pode haver parâmetros de consulta de 0 a n.

iv_p_NAME

(De 0 até n)

String

Parâmetros de caminho

Os parâmetros de caminho fazem parte do endpoint.

Eles são usados para apontar para recursos específicos da REST API.

Pode haver parâmetros de caminho de 0 a n.

is_input

(De 0 até 1)

TY_CODE (tipo de classe)

Parâmetros de estrutura de entrada

Os dados transmitidos como o corpo da solicitação podem ser mapeados usando a estrutura de entrada.

A API REST aceita o payload JSON como o corpo da solicitação. É um parâmetro totalmente digitado que é convertido em payload JSON para a classe de API e o desenvolvedor não precisa trabalhar com JSON.

Consulte os tipos de classe disponíveis para entender os tipos de ABAP para o mapeamento de dados. Por exemplo, o tipo /GOOG/CL_PUBSUB_V1=>TY_041 é mapeado para o recurso REST: Topic, que é transmitido como payload do JSON para o método CREATE_TOPICS.

Um método pode ter no máximo um parâmetro de corpo de solicitação. Alguns métodos não têm um corpo de solicitação.

Como exportar parâmetros

Um método de API é compatível com os seguintes parâmetros de exportação:

Nome do parâmetro	Tipo	Categoria	Descrição
`es_raw`	dados	Saída bruta	Esse parâmetro contém a resposta JSON (Erro ou Sucesso) retornada pelo método da API. Mapeie esse parâmetro para uma variável do tipo String para receber a string de resposta JSON. Nos casos em que a resposta é de qualquer outro tipo, por exemplo, xstring para saída de arquivo em `/goog/cl_storage_v1->get_objects( )`, o parâmetro retorna um valor apropriado. Use esse parâmetro para cenários avançados de solução de problemas ou para cenários avançados da API.
`es_output`	TY_`CODE` (tipo de classe)	Estrutura de saída	A resposta JSON é desserializada para a estrutura ABAP e retornada usando esse parâmetro de exportação digitado. Você pode usá-la como a forma principal de ler as respostas da API usando construções ABAP.
`ev_ret_code`	I (inteiro)	Código de retorno	O código de retorno que pode ser usado para verificar se a execução do método da API conseguiu executar a funcionalidade dele. Para mais informações, consulte Códigos de retorno da API, erros e exceções.
`ev_err_text`	String	Texto do erro	Se a chamada do método falhar, esse parâmetro conterá a mensagem de erro usada para saber o motivo da falha. Para mais informações, consulte Códigos de retorno da API, erros e exceções.
`ev_err_resp`	Tipo de erro = CHAR 60 Descrição do erro = STRING	Resposta de erro	O parâmetro fornece mais informações sobre o erro. Para mais informações, consulte Códigos de retorno da API, erros e exceções.

Tipo de classe

As APIs do Google Cloud usam JSON como o formato principal para a troca de dados. O ABAP SDK for Google Cloud fornece tipos do ABAP que são mapeados para o esquema JSON esperado pelas APIs do Google Cloud.

Esses tipos de ABAP e de tabela relacionados estão disponíveis como tipos de classe em todas as classes de API fornecidas pelo SDK.

O exemplo a seguir mostra o tipo de classe para a classe /GOOG/CL_PUBSUB_V1 da API Pub/Sub.

Tipo de classe

A descrição do tipo de classe TY_041 em /GOOG/CL_PUBSUB_V1 é mapeada para o recurso REST Topic, que é transmitido como JSON Payload para o método CREATE_TOPICS.

Comentários ABAP Doc foram adicionados a todas as classes de API do cliente. Ao usar as ferramentas de desenvolvimento ABAP para SAP NetWeaver (ADT, na sigla em inglês), esses comentários fornecem descrições dos tipos de classe.

Códigos de erro, exceções e retorno da API

Se um erro ocorre quando o método da API da classe ABAP é chamado, o ABAP SDK for Google Cloud transmite as informações de erro para o programa de chamada usando os parâmetros de exportação do SDK ou gerando exceções.

Nome da resposta retornada

Código de retorno da API e erros

As APIs do Google Cloud usam um modelo de erroque oferece experiência consistente em diferentes APIs. Quando um método da Google Cloud API é chamado a partir do SDK, os parâmetros a seguir contêm o código de retorno e as mensagens da API:

ev_ret_code: código de retorno ou código de erro na resposta.
ev_error_text: mensagem de erro na resposta, se houver.
es_raw: resposta de erro bruto, se uma chamada de método de API falhar.

Para verificar o status de uma chamada de API, use o método IS_SUCCESS. É possível usar o valor de ev_ret_code para determinar se uma chamada de API foi bem-sucedida ou não. Em geral, quando ev_ret_code = 2XX, a chamada do método é considerada bem-sucedida. Para todos os outros valores, a chamada do método é considerada malsucedida.

IF lo_client->is_success( ev_ret_code ).
   "Success: Implement custom code
   ELSE
   "Handle the HTTP error status code
ENDIF.

Para algumas APIs da Plataforma Google Maps, se você chamar uma API com entradas inválidas, ela vai retornar um código de status de sucesso HTTP 2XX com uma mensagem e um status de erro. em vez de um código de status de erro HTTP (4XX ou 5XX). A mensagem e o status de erro na resposta da API podem ajudar você a solucionar o problema e corrigir as entradas inválidas.

Para essas APIs da Plataforma Google Maps, além do código de retorno ev_ret_code, verifique a mensagem e o status do erro retornados na resposta da API chamando o método IS_STATUS_OK após a API chamada. O snippet abaixo mostra um exemplo de como usar o método IS_STATUS_OK.

IF lo_client->is_status_ok( ).
  "Success: Implement custom code
  ELSE
  "Handle the HTTP error status code
ENDIF.

O parâmetro es_err_resp fornece mais informações sobre o erro. A tabela a seguir explica os campos no parâmetro es_err_resp.

Campo	Valor
`es_err_resp-error_description`	Mensagem de erro recebida da API. Esse valor é igual ao parâmetro `ev_error_text`.
`es_err_resp-error`	Descrição do status HTTP retornada do cliente HTTP SAP.

Processar erros retornados pelas APIs do Google Cloud

Use as seguintes orientações para processar erros retornados pelas APIs do Google Cloud:

Códigos de erro comuns: para informações sobre erros comuns retornados pelas APIs do Google Cloud e respectivas causas, consulte códigos de erro.
Capturar detalhes do erro: para capturar informações detalhadas do erro com o ABAP SDK for Google Cloud, use o parâmetro de exportação es_raw dos métodos de classe do SDK e mapeie esse parâmetro com uma variável do tipo String. Essa variável contém uma resposta JSON que contém mensagens de erro detalhadas e violações específicas encontradas pelas APIs.

Ver detalhes do erro: para ver informações detalhadas do erro, use um destes métodos:

Depurador: veja o conteúdo da variável que contém a resposta JSON na ferramenta do depurador ABAP para uma análise mais detalhada.

Interface da GUI: use a classe ABAP cl_demo_output=>display( lv_response ) para uma representação visual do erro em um programa de relatório. Se você estiver usando os métodos da API em um programa de relatórios e a execução do programa estiver no modo de primeiro plano, use a classe ABAP cl_demo_output=>display_json( lv_response ).

O snippet de código a seguir ilustra como exibir a resposta da API em caso de erro:

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.

Documentação específica da API: algumas APIs do Google Cloud mostram informações detalhadas sobre erros e orientações para solução de problemas na respectiva documentação individual. Para resolver um erro relacionado a uma API, consulte a documentação específica dessa API, por exemplo, Pub/Sub, Document AI e Cloud Storage.

Exceções

Quando ocorre um erro inesperado durante uma chamada de método da API, como configuração incorreta do SDK ou falha na comunicação HTTP, o SDK gera uma exceção de classe do tipo /GOOG/CX_SDK. Você precisa capturar essa exceção no seu código e escrever uma lógica apropriada de tratamento de erros.

Processar exceção

Você pode receber a mensagem de erro chamando o método get_text da classe de exceção. A mensagem de erro retornada pela classe de exceção tem o seguinte formato:

/GOOG/MSG : Return_Code - Error_Message

A causa das etapas de erro e resolução depende do valor de Return_Code.

Valor de `Return_Code`	Causa do erro	Resolução
`461`	O ABAP SDK for Google Cloud usa um código de retorno especial, `461`, para informar que uma etapa específica de instalação e configuração não foi concluída ou foi concluída incorretamente. `Error_Message` correspondente fornece mais detalhes sobre o erro.	Leia com atenção as instruções de instalação e configuração do SDK e verifique se elas estão corretas.
Qualquer outro valor	Esse código de retorno é o último erro HTTP da classe de cliente SAP padrão. Esse erro indica que o SAP ICM enfrentou um problema de comunicação ao chamar um método da API REST do Google.	Analise cuidadosamente sua rede, firewall, as configurações do SAP ICM e verifique se elas permitem chamadas HTTP para as APIs do Google Cloud.

Para mensagens de erro típicas acionadas no ABAP SDK for Google Cloud e a resolução, consulte o guia de solução de problemas.

Logging

A edição SAP BTP do ABAP SDK for Google Cloud permite registrar mensagens de erro usando um framework de geração de registros incorporado. O objeto de registro /GOOG/LOG_OBJECT e o subobjeto /GOOG/LOG_SUBOBJECT são enviados com o SDK que pode ser usado para criar sua configuração de registro padrão. Para mais informações sobre como criar a configuração padrão de registros, consulte Configurar a geração de registros.

É possível ver os registros de aplicativos usando o app SDK do Google:Exibição de registros de aplicativos. Saiba mais em Ver registros.

Mapeamento de tipo de dados

As tabelas a seguir fornecem uma lista completa de valores type e format compatíveis com o serviço de descoberta de APIs do Google e o tipo de dados ABAP correspondente.

Para mais informações sobre os valores type e format compatíveis com o Serviço de descoberta de APIs do Google, consulte Resumo de tipo e formato.

Valor "Tipo"	Valor do formato	Tipo de dados ABAP	Significado
qualquer		REFERÊNCIA DE TIPO PARA DADOS	A propriedade pode ter qualquer tipo. Definido pela especificação do esquema JSON.
matriz		TIPO DE TABELA COM CHAVES NÃO EXCLUSIVAS	Uma matriz de valores JavaScript. A propriedade "items" indica o esquema dos valores da matriz. Definido pela especificação do esquema JSON.
booleano		ABAP_BOOLEAN	Um valor booleano, "true" ou "false". Definido pela especificação do esquema JSON.
integer	int32	INT4	Um número inteiro assinado de 32 bits Ele tem um valor mínimo de -2.147.483.648 e um valor máximo de 2.147.483.647 (incluso).
integer	uint32	INT4	Um número inteiro sem assinatura de 32 bits. Ele tem um valor mínimo de 0 e um valor máximo de 4.294.967.295 (incluso).
número	double	`/GOOG/NUM_DOUBLE` (string)	Um ponto flutuante IEEE 754 de dupla precisão de 64 bits.
número	float	`/GOOG/NUM_FLOAT` (string)	Um ponto flutuante IEEE 754 de 32 bits de precisão única.
objeto		TYPES	Um objeto JavaScript. Definido pela especificação do esquema JSON.
string		STRING	Uma string arbitrária. Definido pela especificação do esquema JSON.
string	byte	STRING	Uma string de bytes preenchida e codificada em base64, codificada com um URL e alfabeto seguro de nome de arquivo (às vezes chamado de "seguro para Web" ou "base64url"). Definido pela RFC 4648.
string	data	STRING	Uma data RFC 3339 no formato AAAA-MM-DD. Definido na especificação do Esquema JSON.
string	date-time	STRING	Um carimbo de data/hora RFC 3339 no horário UTC. Isso está no formato aaaa-MM-ddTHH:mm:ss.SSSZ. A parte de milissegundos (".SSS") é opcional. Definido na especificação do Esquema JSON.
string	google-datetime	STRING	Um carimbo de data/hora RFC 3339 no horário UTC. Isso está no formato aaaa-MM-ddTHH:mm:ss.SSSZ. A parte de milissegundos (".SSS") é opcional.
string	google-duration	STRING	Uma string termina com o sufixo "s" (indicando segundos) e é precedida pelo número de segundos, com nanossegundos expressos como segundos fracionários. O ponto é sempre usado como um separador decimal, não uma vírgula.
string	google-fieldmask	STRING	Uma string em que os nomes de campos são separados por uma vírgula. Os nomes dos campos são representados em convenções de nomenclatura de letras minúsculas.
string	int64	STRING	Um número inteiro assinado de 64 bits Ele tem um valor mínimo de -9.223.372.036.854.775.808 e um valor máximo de 9.223.372.036.854.775.807 (incluso).
string	uint64	STRING	Um número inteiro sem assinatura de 64 bits. Ele tem um valor mínimo de 0 e um valor máximo de (2^64)-1 (incluso).

Serialização e desserialização de solicitações e respostas da API

Por padrão, a edição SAP BTP do SDK ABAP para Google Cloud cuida do gerenciamento e do despacho de solicitações e respostas de API. Cada classe ABAP de uma API do Google Cloud tem tipos incorporados de ABAP para formar a entrada e a saída dos métodos. Para implementar uma transformação personalizada de solicitação e resposta, use o ponto de melhoria com as definições do Business Add-In (BAdI) do SAP que são enviadas com o SDK.

Implementar uma transformação personalizada

O ponto de melhoria /GOOG/ES_TRANSFORM_JSON, que é enviado com o SDK, inclui as seguintes definições de BAdI:

/GOOG/BADI_SERIALIZE_JSON: para implementar a lógica de serialização personalizada.
/GOOG/BADI_DESERIALIZE_JSON: para implementar a lógica de desserialização personalizada.

Você pode escrever uma lógica de transformação específica nas implementações desses BAdIs. As interfaces desses BAdIs têm IV_METHOD_NAME como o parâmetro de importação. Use esse parâmetro para separar a lógica de transformação de cada API e método de API usando blocos IF….ENDIF. No bloco de implementação, defina o parâmetro de exportação EV_HANDLED como X.

Para implementar uma transformação personalizada, siga estas etapas:

Para /GOOG/BADI_SERIALIZE_JSON, crie uma implementação de melhoria:
- Para transformar as solicitações de API, crie uma implementação para o BAdI /GOOG/BADI_SERIALIZE_JSON com uma classe de implementação.
- Para transformar as respostas da API, crie uma implementação para o BAdI /GOOG/BADI_DESERIALIZE_JSON com uma classe de implementação.
Determine o ID do método da API em que você precisa gravar a transformação. O ID do método é uma concatenação do seguinte:
- O valor da constante C_SERVICE_NAME do atributo de classe.
- O caractere #.
- A descrição do método da classe de API em que você precisa implementar a transformação.
Por exemplo, para gravar transformações para publicar mensagens em um tópico do Pub/Sub, o ID do método seria: pubsub:v1#pubsub.projects.topics.publish
Na implementação do método do BAdI:
1. No ID do método, escreva sua transformação personalizada em IF….ENDIF block.
2. Defina o parâmetro de exportação EV_HANDLED como X.
  
  Se EV_HANDLED não estiver definido como X, a lógica padrão de marshalling e unmarshalling do SDK será aplicada.
Marque o API State da classe de implementação como Use System-Internally (Contract C1). A lógica de transformação personalizada é invocada durante o ambiente de execução. A lógica padrão de serialização e desserialização enviada com o SDK seria ignorada.

Namespace

Todo o código fornecido pelo Google é colocado no namespace reservado /GOOG/.

Receber suporte

Se você precisar de ajuda para resolver problemas com o ABAP SDK for Google Cloud, faça o seguinte:

Consulte o guia de solução de problemas do ABAP SDK for Google Cloud.
Faça suas perguntas e discuta o ABAP SDK for Google Cloud com a comunidade nos Fóruns do Cloud.
Colete todas as informações de diagnóstico disponíveis e entre em contato com o Cloud Customer Care. Para mais informações sobre como entrar em contato com o atendimento ao cliente, consulte Como receber suporte para o SAP no Google Cloud.