将 SAP 通知发送到 Google Chat

本文档介绍了一种参考架构，用于通过本地或任何云版本的 ABAP SDK for Google Cloud 构建适用于 SAP 的 Google Chat 应用。借助 Chat 应用，您可以将 SAP 流程和工作流引入 Google Chat，让用户能够在 Google Workspace 中接收通知，例如报警报告、工作流提醒、系统提醒和作业完成更新。

本文档的目标受众群体包括 ABAP 开发者、SAP 解决方案架构师和云架构师。本文档假定您熟悉 Google Workspace 中提供的 Chat 应用。

架构

下图显示了为 SAP 实现单向 Chat 应用的参考架构，该架构可从 SAP ERP 系统向 Chat 聊天室发送消息：

适用于 SAP 的 Chat 应用

此参考架构包括以下组件：

#	组件	详细信息
1	SAP 流程或事务	需要发送用户通知的任何 SAP 流程或事务。这是通过 Google Chat 触发通信的起点。
2	ABAP SDK for Google Cloud	充当 SAP 系统与 Google Cloud之间的桥梁，以便通过 Google Chat API 进行安全的 HTTPS 通信。
3	Google Chat 应用项目	您已启用 Google Chat API 并配置 Chat 应用的 Google Cloud 项目。
4	Chat 聊天室	Google Chat 中的专用聊天室，您的 SAP 系统可在其中与用户进行沟通。 Chat 应用驻留在此聊天室中，通过 Google Chat API 提供来自 SAP 系统的实时信息流。

使用的产品

此参考架构使用以下 Google 产品：

ABAP SDK for Google Cloud：可帮助您开发 ABAP 应用，将您的 SAP 系统与 Google Chat 等 Google Cloud 服务相关联。
Google Chat：可帮助您创建互动式协作式 Chat 应用，从而提升沟通效率和工作效率。

使用场景

单向 Chat 应用是非交互式应用，可让您向 Chat 聊天室用户发送消息，但用户无法回复 Chat 应用。下图说明了单向 Chat 应用的聊天模式：

聊天应用模式

以下列表展示了 Google Chat for SAP 的一些用例：

工作流事件通知：您可以针对工作流程中涉及的不同步骤向 Chat 应用发送消息，以提醒 Chat 聊天室中存在的特定用户组。例如，用户批准或拒绝采购订单。
系统提醒：您可以向 Chat 聊天室发送提醒，以便系统管理员了解各种系统阈值是否已达到。例如，磁盘空间使用情况、长时间运行的操作、缓存锁定或许可到期。
作业状态更新：您可以向一组等待这些作业完成并执行后期处理操作的用户发送长时间运行的自定义作业的更新。

设计考虑事项

在为您的用例设计 Chat 应用时，有几个因素可能会影响您的设计决策。本部分提供的指导可帮助您使用此参考架构开发满足特定安全性、隐私性、合规性和费用要求的架构。

Google Chat 应用配置

Chat 应用名称：为您的 Chat 应用提供清晰且有意义的名称。为提供顺畅的用户体验，请确保您的 Chat 应用名称准确反映其功能或其集成的服务。
时区：Chat 聊天室可由属于不同时区的成员共享。因此，请务必将 Chat 应用配置为在所有聊天室用户都方便的时间传输消息。或者，对于重要提醒或通知，您可以将成员指定到具有共用时区的 Chat 聊天室，并构建逻辑以确定 Chat 应用可以向哪个聊天室发送消息。

安全性、隐私权和合规性

为了保持机密性，必须严格控制在 Chat 聊天室内共享敏感信息，例如客户联系详细信息、IBAN 或其他需要知晓的数据。此外，当向 Chat 应用添加了 Chat 聊天室的新用户时，务必要制定明确的规定，以确保对此类活动进行适当管理。

您还可以考虑使用 Cloud Data Loss Prevention (DLP) API 来对消息内容进行脱敏处理。如需了解如何使用 DLP API 保护 SAP 中的敏感企业数据，请参阅使用 DLP API 保护 SAP 中的数据。

为了确保安全，请确保 Google Workspace 管理员遵循 Google 推荐的最佳做法。

配额和限制

Google Chat API 是一项共享服务，因此适用配额和限制。如果您超出配额，则会收到 429: Too many requests HTTP 状态代码响应。如需详细了解配额和限制，请参阅使用限制。

Google Chat API 本身没有任何使用费，但 Google Chat 是 Google Workspace 产品。Google Workspace 是一套捆绑式办公协作工具，包含 Gmail、文档、表格、幻灯片、Google Chat 应用等。其定价结构是整体的，这意味着您无法选择和购买单个组件。如需详细了解价格，请参阅 Google Workspace 价格。

设计替代方案

虽然本文档主要介绍本地版本或任何云版本的 ABAP SDK for Google Cloud，但您也可以使用 SAP BTP 版本的 ABAP SDK for Google Cloud 获得类似的结果。您可以调整所提供的资源，以在 SAP BTP 环境中构建类似的解决方案。

准备工作

在根据此参考架构实现解决方案之前，确保您已完成以下前提条件：

您拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。
您拥有一个 Google Cloud 账号和项目。每个 Chat 应用都需要自己的 Google Cloud 项目。这意味着您只能在一个 Google Cloud 项目中配置一个 Chat 应用。
您的项目已启用结算功能。如需了解如何确认您的项目是否已启用结算功能，请参阅验证项目的结算状态。
已安装并配置本地版本或任何云版本的 ABAP SDK for Google Cloud。
您的 Google Cloud 项目中已启用 Google Chat API。

配置 Google Chat 应用

在 Google Cloud 控制台中，搜索“Google Chat API”，然后点击 Google Chat API，再点击管理。

前往 Chat API
点击配置并设置 Google Chat 应用：
1. 在应用名称中，输入 Quickstart SAP App。
2. 在头像网址中，输入 https://developers.google.com/chat/images/quickstart-app-avatar.png。
3. 在说明中，输入 Quickstart app for SAP。
停用互动功能。
点击保存。

为 Google Chat 应用设置身份验证

您可以通过两种方式对 Google Chat 应用进行身份验证：以应用本身或用户的身份进行身份验证。

当您的应用需要执行自动化任务（例如在不直接与用户互动的情况下发送系统通知）时，它会使用服务账号。如果您希望应用代表用户执行操作，例如以特定用户的名义发送消息，则需要进行用户身份验证。这种双重身份验证方法可让您灵活地控制应用与 Google Chat 的互动方式。

借助 ABAP SDK for Google Cloud，您可以设置这两种身份验证方式。如需了解如何为 Google Chat 应用设置身份验证，请参阅：

以 Google Chat 应用的身份进行身份验证：使用访问令牌进行身份验证或使用 JSON Web 令牌进行身份验证
以 Google Chat 用户身份进行身份验证和授权：使用 OAuth 2.0 客户端凭证向 Google Workspace API 进行身份验证

如需了解 Google Chat API 方法及其支持的授权范围，请参阅对 Chat 应用和 Google Chat API 请求进行身份验证和授权。

本文档中所述的参考架构使用 Chat 应用作为身份验证方式，并使用访问令牌进行身份验证。

如需将 Chat 应用设置为身份验证应用，请执行以下步骤：

在 Google Cloud 控制台中，配置 OAuth 权限请求页面并选择范围。
在 Google Cloud 控制台中，创建服务账号。
可选：为您的服务账号分配角色，以授予对 Google Cloud 项目资源的访问权限。如需了解详情，请参阅管理对服务账号的访问权限。

在 SAP 系统中，使用以下详细信息配置客户端密钥：

字段	说明
Google Cloud 密钥名称	指定客户端密钥配置的名称。例如 `ABAP_SDK_CHAT`。
Google Cloud 服务账号名称	指定您已授予 Google Chat API 访问权限的服务账号的名称。例如 `sap-example-svc-acct@example-project-123456.iam.gserviceaccount.com`。
Google Cloud 范围	指定 API 访问权限范围：`https://www.googleapis.com/auth/chat.bot`。
Google Cloud 项目标识符	指定包含已启用的 Google Chat API 的 Google Cloud 项目的 ID。
命令名称	将此字段留空。
授权类	视情况指定授权类：如需使用访问令牌进行身份验证，请使用以下代码：`/GOOG/CL_AUTH_GOOGLE` 如需使用 JWT 进行身份验证，请使用：`/GOOG/CL_AUTH_JWT`
令牌缓存	此标志用于确定是否已缓存从 Google Cloud 检索到的访问令牌。我们建议您在完成与 Google Cloud的连接的配置和测试后启用令牌缓存。如需详细了解令牌缓存，请参阅启用令牌缓存。
令牌刷新秒数	访问令牌在多久后（以秒为单位）会到期并且必须刷新。默认值为 `3500`。
授权参数 1	将此字段留空。
授权参数 2	将此字段留空。

如需了解设置身份验证的详细步骤，请参阅使用访问令牌进行身份验证或使用 JSON Web 令牌进行身份验证。

将 Google Chat 应用添加到聊天室

打开 Google Chat 应用或 Gmail 应用。
将聊天应用添加到 Chat 聊天室。如需了解如何执行此操作，请参阅将应用添加到对话或聊天室。

从 ABAP 环境发送消息

Google Chat 和 Chat 应用使用基于 JSON 的消息格式，每条消息都包含用户 ID、样式和内容等详细信息。聊天应用可以发送以下类型的消息：

短信：短信包含用于传达基本信息的纯文本内容。
卡片消息：卡片消息用于定义要在聊天室中显示的卡片的格式、内容和行为。例如，卡片消息可以包含一个包含链接的按钮，该链接会打开一个对话框，用于从用户那里收集信息。

如需详细了解 Google Chat 消息，请参阅 Google Chat 消息概览。

如需使用 ABAP SDK for Google Cloud 将消息从 SAP 系统发送到 Chat 聊天室，您可以使用 /GOOG/CL_CHAT_V1 类的 CREATE_MESSAGES 方法。

发送短信

以下代码示例展示了如何从 SAP 系统向 Chat 聊天室发送短信：

REPORT zsend_text_message.

DATA lv_client_key TYPE /goog/keyname.
DATA ls_input      TYPE /goog/cl_chat_v1=>ty_072.
DATA lv_space_id   TYPE string.

lv_client_key = 'CLIENT_KEY'.
ls_input-text = 'TEXT_MESSAGE'.
lv_space_id   = 'SPACE_ID'.

TRY.
    DATA(lo_chat) = NEW /goog/cl_chat_v1( iv_key_name = lv_client_key ).
  CATCH /goog/cx_sdk INTO DATA(lo_excp).
    " Handle exception here
ENDTRY.

TRY.
    lo_chat->create_messages( EXPORTING iv_p_spaces_id = lv_space_id
                                        is_input       = ls_input
                              IMPORTING ev_ret_code    = DATA(return_code)
                                        ev_err_text    = DATA(error_text)
                                        es_err_resp    = DATA(err_resp) ).
  CATCH /goog/cx_sdk INTO lo_excp.
    " Handle exception here
ENDTRY.

IF /goog/cl_chat_v1=>is_success( iv_code = return_code ) = abap_true.
  " Handle success here
ELSE.
  " Handle error here
ENDIF.

替换以下内容：

CLIENT_KEY：为身份验证配置的客户端密钥。
TEXT_MESSAGE：要发送到 Chat 聊天室的文本消息。
SPACE_ID：Chat 聊天室的唯一标识符 ID。如需找到 Chat 聊天室 ID，请在网络浏览器中打开 Google Chat 聊天室。您可以在网址中找到该 ID，如以下屏幕截图所示：

发送卡片消息

卡片是一种视觉吸引力强且富有互动性的信息呈现方式，可提升整体用户体验。这些元素可以包含标题、图片、按钮等，让用户能够直接在聊天界面中与内容互动。例如，采购订单工作流卡片可能包含以下信息：

采购订单编号
票据日期
文档类型
供应商
运费类型

如需使用 ABAP SDK for Google Cloud 开发卡片，请使用 GitHub 代码库中的自定义接口 ZGOOG_IF_CHAT_CARDS_V2。此自定义接口包含创建卡片所需的 ABAP 类型。您可以构建卡片，例如以下订单工作流示例卡片：

Chat 应用卡片

如需详细了解如何设计卡片式消息，请参阅为 Google Chat 应用构建卡片。

以下代码示例说明了如何将卡片消息从 SAP 系统发送到 Chat 聊天室：

REPORT zsend_card_message.

DATA lv_client_key TYPE /goog/keyname.
DATA ls_input      TYPE /goog/cl_chat_v1=>ty_072.
DATA lv_space_id   TYPE string.
DATA ls_widget     TYPE zgoog_if_chat_cards_v2=>ty_widget.
DATA ls_section    TYPE zgoog_if_chat_cards_v2=>ty_sections.
DATA ls_card_v2    TYPE zgoog_if_chat_cards_v2=>ty_cards_v2.
DATA ls_card       TYPE /goog/cl_chat_v1=>ty_012.
DATA ls_rb         TYPE zgoog_if_chat_cards_v2=>ty_selection_item.
DATA ls_button     TYPE zgoog_if_chat_cards_v2=>ty_button.
DATA ls_param      TYPE zgoog_if_chat_cards_v2=>ty_action_parameters.

lv_client_key = 'CLIENT_KEY'.
lv_space_id   = 'SPACE_ID'.

TRY.

    DATA(lo_chat) = NEW /goog/cl_chat_v1( iv_key_name = lv_client_key ).
  CATCH /goog/cx_sdk INTO DATA(lo_excp).
    " Handle exception here
ENDTRY.

" Building the Card Structure

" Set the header
ls_card_v2-header = VALUE zgoog_if_chat_cards_v2=>ty_header(
                              title     = 'Purchase Order Workflow - Level 2 Approval Alert!'
                              subtitle  = 'PO Number: 8700000034'
                              image_url = 'https://developers.google.com/chat/images/quickstart-app-avatar.png' ).

" Create sections
ls_section-header = 'Purchase Order Details'.

ls_widget-decorated_text = VALUE zgoog_if_chat_cards_v2=>ty_decorated_text(
                                     icon = VALUE zgoog_if_chat_cards_v2=>ty_icon( known_icon = 'INVITE' )
                                     text = 'Document Date: 2024-10-23' ).
ls_section-widgets = VALUE #( ( ls_widget ) ).
CLEAR ls_widget.

ls_widget-decorated_text = VALUE zgoog_if_chat_cards_v2=>ty_decorated_text(
    icon = VALUE zgoog_if_chat_cards_v2=>ty_icon(
                     material_icon = VALUE zgoog_if_chat_cards_v2=>ty_material_icon( name = 'category' ) )
    text = 'Document Type: Standard PO'  ).

ls_section-widgets = VALUE #( BASE ls_section-widgets
                              ( ls_widget ) ).
CLEAR ls_widget.

ls_widget-decorated_text = VALUE zgoog_if_chat_cards_v2=>ty_decorated_text(
    icon = VALUE zgoog_if_chat_cards_v2=>ty_icon(
                     material_icon = VALUE zgoog_if_chat_cards_v2=>ty_material_icon( name = 'conveyor_belt' ) )
    text = 'Supplier: 5300000061 - Cymbal Industries'  ).

ls_section-widgets = VALUE #( BASE ls_section-widgets
                              ( ls_widget ) ).
CLEAR ls_widget.

ls_widget-decorated_text = VALUE zgoog_if_chat_cards_v2=>ty_decorated_text(
                                     icon = VALUE zgoog_if_chat_cards_v2=>ty_icon( known_icon = 'TRAIN' )
                                     text = 'Shipping Type: RAIL' ).
ls_section-widgets = VALUE #( BASE ls_section-widgets
                              ( ls_widget ) ).
CLEAR ls_widget.

ls_widget-decorated_text = VALUE zgoog_if_chat_cards_v2=>ty_decorated_text( text = 'Approved By: User-Name' ).
ls_section-widgets = VALUE #( BASE ls_section-widgets
                              ( ls_widget ) ).
CLEAR ls_widget.

ls_section-widgets = VALUE #( BASE ls_section-widgets
                              ( ls_widget ) ).

ls_card_v2-sections = VALUE #( ( ls_section ) ).

ls_card-card = REF #( ls_card_v2 ).
ls_input-cards_v2 = VALUE #( (  ls_card ) ).

TRY.
    lo_chat->create_messages( EXPORTING iv_p_spaces_id = lv_space_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) ).
  CATCH /goog/cx_sdk INTO lo_excp.
    " Handle exception here
ENDTRY.

IF lo_chat->is_error( lv_ret_code ).
  " Handle error here
ELSE.
  " Handle success here
ENDIF.