Receber um evento do Cloud Pub/Sub no SAP usando o SDK do ABAP para o Google Cloud

1. Introdução

Este codelab mostra como receber detalhes de eventos de um tópico do Google Cloud Pub/Sub usando o ABAP SDK for Google Cloud. Vamos usar os seguintes serviços do Google Cloud:

• Cloud Pub/Sub
• Cloud Shell

Pré-requisitos

• Verifique se você tem acesso a um sistema SAP com o ABAP SDK for Google Cloud instalado.
• Consulte o codelab " Instalar a versão de teste da plataforma ABAP no Google Cloud Platform e instalar o SDK do ABAP" para configurar um novo sistema.
• Você criou um tópico PUBSUB_DEMO_TOPIC como parte do codelab " Enviar eventos do SAP para o Pub/Sub usando o SDK do ABAP" no seu projeto do Google Cloud. Se não tiver sido criado, use o comando abaixo:

gcloud pubsub topics create PUBSUB_DEMO_TOPIC

O que você vai criar

Você vai criar o seguinte:

• Uma conta de serviço com permissões de "Assinante" para interagir com a API Pub/Sub.
• Um programa ABAP para receber e confirmar mensagens do seu tópico do Pub/Sub.

2. Requisitos

• Navegadores, como o Chrome ou o Firefox.
• Um projeto do Google Cloud com o faturamento ativado ou crie uma conta de teste sem custo financeiro de 90 dias para o Google Cloud Platform.
• A GUI do SAP (Windows ou Java) instalada no seu sistema. Se a GUI do SAP já estiver instalada no seu notebook, conecte-se ao SAP usando o endereço IP externo da VM como o IP do servidor de aplicativos. Se você estiver usando um Mac, também poderá instalar a GUI do SAP para Java disponível neste link.

3. Antes de começar

• No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud (por exemplo, abap-sdk-poc).
• Verifique se o faturamento está ativado no seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto. Pule esta etapa se você estiver usando a conta de teste sem custo financeiro de 90 dias.
• Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. No console do Cloud, clique em Ativar o Cloud Shell no canto superior direito:

• Execute os comandos a seguir para autenticar sua conta e definir o projeto padrão como abap-sdk-poc. A zona us-west4-b é usada como exemplo. Se necessário, mude o projeto e a zona nos comandos a seguir de acordo com sua preferência.

gcloud auth login
gcloud config set project abap-sdk-poc
gcloud config set compute/zone us-west4-b

• Como parte do codelab anterior " Enviar evento para o Pub/Sub", você já deve ter ativado a API Pub/Sub, criado o tópico e publicado mensagens no Pub/Sub.

4. Criar uma conta de serviço para acesso ao Pub/Sub

Usar uma conta de serviço com a função Subscriber é a maneira mais segura de o programa ABAP receber mensagens do Pub/Sub. Essa função limita as permissões apenas à recuperação de mensagens, evitando possíveis vulnerabilidades de segurança.

Criar a conta de serviço

Para criar uma conta de serviço com a função necessária, siga estas etapas:

1. Execute o seguinte comando no terminal do Cloud Shell:

gcloud iam service-accounts \
create abap-sdk-pubsub-subscriber \
--display-name="Service Account for Pub/Sub Subscriber"

Observação: se o comando acima for executado com sucesso, você vai receber a seguinte resposta:

Created service account [abap-sdk-pubsub-subscriber] .

2. Agora, adicione os papéis necessários à conta de serviço criada na etapa acima:

gcloud projects add-iam-policy-binding abap-sdk-poc \
--member='serviceAccount:[e-mail]' \
--role='roles/pubsub.subscriber'

O comando acima usa abap-sdk-poc como um marcador de posição para o projeto do Google Cloud. Substitua abap-sdk-poc pelo ID do projeto.

3. Para verificar se a função foi adicionada, acesse a página IAM. A conta de serviço criada vai aparecer com a função atribuída a ela.

5. Noções básicas sobre assinaturas pull

Em uma assinatura de pull, seu sistema SAP atua como o cliente assinante e inicia solicitações a um servidor do Pub/Sub para recuperar mensagens. O cliente assinante usa a API REST Pull.

Principais métodos da API

API Google Cloud Pub/Sub

• pull: inicia uma solicitação para buscar mensagens.
• acknowledge: sinaliza ao Pub/Sub que uma mensagem foi processada com sucesso.

Equivalentes do ABAP SDK for Google Cloud

• /GOOG/CL_PUBSUB_V1 -> PULL_SUBSCRIPTIONS
• /GOOG/CL_PUBSUB_V1 -> ACKNOWLEDGE_SUBSCRIPTIONS

Fluxo de mensagens para uma assinatura de pull

A imagem a seguir mostra o fluxo de trabalho entre um cliente assinante e uma assinatura de extração.

1. Solicitação de pull:seu sistema SAP (o assinante) usa o método pull para solicitar mensagens do servidor do Pub/Sub.
2. Resposta de extração: o servidor do Pub/Sub responde com zero ou mais mensagens e IDs de confirmação. Uma resposta com zero mensagens ou com um erro não indica necessariamente que não há mensagens disponíveis para receber. Essa resposta é o PullResponse, conforme mostrado na imagem.
3. Confirmação:depois de processar uma mensagem, seu sistema SAP usa o método de confirmação com o ID de confirmação recebido. Isso impede que o Pub/Sub reenvie a mensagem.

6. Configurar sua assinatura e enviar mensagens

Criar uma assinatura de pull

• Execute este comando gcloud para criar uma assinatura de extração chamada PUBSUB_DEMO_SUBSCRIPTION que vai receber mensagens do PUBSUB_DEMO_TOPIC:

gcloud pubsub subscriptions create PUBSUB_DEMO_SUBSCRIPTION \
--topic=PUBSUB_DEMO_TOPIC

Publicar mensagens

Escolha um destes métodos para enviar mensagens para PUBSUB_DEMO_TOPIC:

• Reutilize seu programa:se você tiver o programa de um codelab anterior para publicação, use-o.
• Publicação direta: para um teste rápido, tente uma das seguintes opções:
• Console do Cloud: publique diretamente no Console do Google Cloud. Para mais detalhes, consulte a documentação do Pub/Sub.
• Comando gcloud: execute o seguinte comando:

gcloud pubsub topics publish PUBSUB_DEMO_TOPIC \
--message='{"eventType":"SalesOrderChanged","source":"SAPDEV100","eventTime":"20240207183048","SalesOrder":1000924}'

Observação: uma publicação de mensagem bem-sucedida retorna um ID de mensagem.

7. Criar configuração de chave do cliente

Agora que você configurou os pré-requisitos no Google Cloud, podemos continuar com a configuração no SAP.

Para a configuração relacionada à autenticação e conectividade, o ABAP SDK for Google Cloud usa as tabelas /GOOG/CLIENT_KEY e /GOOG/SERVIC_MAP..

Para manter a configuração na tabela /GOOG/CLIENT_KEY, siga estas etapas:

1. Na GUI do SAP, insira o código da transação SPRO.
2. Clique em IMG de referência SAP.
3. Clique em ABAP SDK for Google Cloud > Configurações básicas > Configurar chave do cliente.

4. Mantenha os seguintes valores nos campos. Não preencha os outros campos.

Campo	Valor
Nome da chave do Google Cloud	PUBSUB_SUBSCRIBER
Nome da conta de serviço do Google Cloud	[e-mail]
Escopo do Google Cloud	https://www.googleapis.com/auth/cloud-platform
ID do projeto	abap-sdk-poc
Classe de autorização	/GOOG/CL_AUTH_GOOGLE

Observação: a configuração da tabela /GOOG/SERVIC_MAP é opcional e pode ser ignorada neste caso.

8. Criar um relatório ABAP para receber mensagens do Google Cloud Pub/Sub

1. Faça login no sistema SAP.
2. Acesse o código da transação SE38 e crie um programa de relatórios com o nome ZDEMO_RECEIVE_CPS_EVENTS..
3. No pop-up que abrir, forneça os detalhes conforme mostrado abaixo e clique em Salvar.

4. No próximo pop-up, selecione Objeto local ou forneça um nome de pacote, conforme apropriado.
5. No editor ABAP, adicione o seguinte código:

REPORT zdemo_receive_cps_events.

TYPES: BEGIN OF ty_event_message,
         event_time  TYPE timestamp,
         event_type  TYPE char30,
         source      TYPE char30,
         sales_order TYPE vbeln,
       END OF ty_event_message.

DATA: ls_input     TYPE /goog/cl_pubsub_v1=>ty_026,
      ls_input_ack TYPE /goog/cl_pubsub_v1=>ty_001,
      ls_event_msg TYPE ty_event_message.

TRY.

    "Open HTTP Connection
    DATA(lo_client) = NEW /goog/cl_pubsub_v1( iv_key_name = 'PUBSUB_SUBSCRIBER' ).

    "Populate relevant parameters
    " Derive project id from the client object
    DATA(lv_p_projects_id) = CONV string( lo_client->gv_project_id ).
    " Name of the subscription from where we want to pull data
    DATA(lv_p_subscriptions_id) = CONV string( 'PUBSUB_DEMO_SUBSCRIPTION' ).
    " Max number of messages that will be received in 1 API call
    ls_input-max_messages = 1.

    "Call API method: pubsub.projects.subscriptions.pull
    lo_client->pull_subscriptions(
      EXPORTING
        iv_p_projects_id      = lv_p_projects_id
        iv_p_subscriptions_id = lv_p_subscriptions_id
        is_input              = ls_input
      IMPORTING
        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 lo_client->is_success( lv_ret_code ).
      DATA(ls_received_msg) = VALUE #( ls_output-received_messages[ 1 ] OPTIONAL ).
      IF ls_received_msg IS NOT INITIAL.
        "Messages published to Pub/Sub should be base-64 encoded, hence in order to get the exact message, we need to decode the data field.
        "However, attributes published to Pub/Sub should be accessible as data references.
        DATA(lv_msg) = |{ cl_http_utility=>decode_base64( encoded = ls_received_msg-message-data ) }|.
        /ui2/cl_json=>deserialize( EXPORTING json          = lv_msg
                                             pretty_name   = /ui2/cl_json=>pretty_mode-extended
                                   CHANGING  data          = ls_event_msg ).

        cl_demo_output=>new( )->begin_section( |Receive Events from Cloud Pubsub using ABAP SDK for Google Cloud|
        )->write_text( |The below event was successfully received with message ID { ls_received_msg-message-MESSAGE_ID }|
        )->write_data( ls_event_msg
        )->end_section(
        )->display( ).

        ls_input_ack-ack_ids = VALUE #( ( ls_received_msg-ack_id ) ).

        "Call API method: pubsub.projects.subscriptions.acknowledge
        "Acknowledge the messages so it is not pulled again.
        lo_client->acknowledge_subscriptions(
          EXPORTING
            iv_p_projects_id      = lv_p_projects_id
            iv_p_subscriptions_id = lv_p_subscriptions_id
            is_input              = ls_input_ack
          IMPORTING
            es_output             = DATA(ls_output_ack)
            ev_ret_code           = lv_ret_code
            ev_err_text           = lv_err_text
            es_err_resp           = ls_err_resp ).

        IF lo_client->is_success( lv_ret_code ).
          MESSAGE lv_msg TYPE 'S'.
        ELSE.
          MESSAGE lv_err_text TYPE 'E'.
        ENDIF.
      ELSE.
        MESSAGE 'No Messages were received!' TYPE 'S'.
      ENDIF.
    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.

6. Salve e ative o relatório.
7. Execute o relatório (F8).

Se a execução for bem-sucedida, você vai ver a saída do relatório, conforme mostrado abaixo:

9. Explicação do código do assinante do Pub/Sub em ABAP

Essencialmente, esse programa ABAP se integra ao Google Cloud Pub/Sub como um assinante de mensagens. Ele verifica uma assinatura especificada para novas mensagens sob demanda, as processa e confirma o recebimento para evitar uma nova entrega no futuro.

O programa vai realizar as seguintes atividades:

Detalhamento passo a passo

Estabelecer conexão:

• Ele estabelece uma conexão HTTP com o serviço Google Cloud Pub/Sub usando a classe /GOOG/CL_PUBSUB_V1.

Definir parâmetros:

• ID do projeto: extrai o ID do projeto relevante em que a assinatura do Pub/Sub reside.
• Nome da assinatura:especifica o nome da assinatura de que as mensagens serão extraídas (PUBSUB_DEMO_SUBSCRIPTION).
• Limite de mensagens: define o número máximo de mensagens a serem recuperadas em uma única chamada de API (neste caso, 1).

Buscar mensagens:

• Chama o método pull_subscriptions para recuperar mensagens da assinatura especificada.

Processar mensagens recebidas:

• Se houver mensagens, o programa vai decodificar os dados, registrar o conteúdo e enviar um reconhecimento.

Confirmar mensagens:

• Chama o método acknowledge_subscriptions para enviar uma confirmação ao Pub/Sub indicando o recebimento das mensagens. Isso impede que eles sejam entregues novamente.

Tratar sucesso/erros:

• Fornece mensagens de sucesso se as mensagens forem recebidas e confirmadas e mostra mensagens de erro para vários cenários de falha (nenhuma mensagem recebida, erros de API etc.).

Encerrar conexão:

• Fecha a conexão HTTP com o serviço Pub/Sub.

10. Parabéns

Excelente trabalho ao concluir o codelab "Receber um evento do Cloud Pub/Sub usando o SDK ABAP para Google Cloud".

Você criou uma ponte entre o ABAP e o Google Cloud Pub/Sub. A conclusão do codelab demonstra um conhecimento sólido de mensagens orientadas a eventos e como usar o ABAP SDK for Google Cloud para integrar aos serviços do Google Cloud. Muito bem!

Você desbloqueou um novo nível de integração entre o ABAP e os serviços do Google Cloud. Amplie seus horizontes com estas opções incríveis:

• Usar a API Translation com o ABAP SDK for Google Cloud
• Fazer upload de um objeto grande para um bucket do Cloud Storage usando a divisão em partes
• Como recuperar credenciais/secrets do Secret Manager com o ABAP SDK for Google Cloud
• Chamar o test-bison da Vertex AI em ABAP
• Chamar o BigQuery ML do ABAP

11. Limpar

Se você não quiser continuar com os outros codelabs relacionados ao ABAP SDK for Google Cloud, faça a limpeza.

Excluir o projeto

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

• Exclua o projeto do Google Cloud:

gcloud projects delete abap-sdk-poc

Excluir recursos individuais

1. Exclua a instância de computação:

gcloud compute instances delete abap-trial-docker

2. Exclua as regras de firewall:

gcloud compute firewall-rules delete sapmachine

3. Exclua a conta de serviço:

gcloud iam service-accounts delete \
    [e-mail]