GSMA Open Gateway Operate APIs 技术实现指南 V2.0
1. 引言
1.1 概述
GSMA Open Gateway (OGW) 平台是 GSMA Operator Platform 的一种部署选项，旨在通过标准化 API 实现运营商之间统一、标准化的服务交付和管理，增强互操作性，简化服务管理，并促进创新，确保跨不同网络的用户体验无缝且一致。
1.2 范围
本指南旨在为运营商、渠道合作伙伴和科技合作伙伴等利益相关者提供技术集成指南，帮助他们部署和使用 GSMA Open Gateway 服务 API。指南涵盖了 API 产品目录检索、API 产品订购和 API 产品使用检索等方面的 Operate API 利用。
1.2.1 目标受众
- 运营商：负责管理网络服务的团队。
- 渠道合作伙伴：提供跨多个运营商的捆绑服务的实体。
- 监管机构：负责监督行业标准和法规合规性的机构。
1.3 定义
定义了关键术语，如应用程序、应用程序所有者、审批状态、渠道合作伙伴、开放网关平台、运营商、服务 API 等。
1.4 缩写
列出了文档中使用的缩写，如 API、ASP、CSP、CNPJ、EU、GDPR、HTTP、IETF、ISO、ITU、JSON、JWKS、JWT、MNO、MSISDN、OAS、OAuth、OGW、OIDC、REST、TMF、URI、URL、UUID、VAT 等。
1.5 参考文献
列出了文档中引用的参考文献，包括 GSMA 和 TM Forum 的相关文档以及 RFC 文档。
1.6 术语约定
解释了文档中使用的术语，如“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”。
2. 聚合模式
2.1 聚合模式架构
在 Open Gateway 聚合模式下，渠道合作伙伴通常按国家进行登出，一些本地运营商使用这些 Operate API。API 产品提供和技术规范在 TMF936 产品目录 API 中定义。通过 TMF931 登出 API，客户端应用程序在每个运营商上进行配置，并使用产品订单请求 API 产品提供。聚合器通常会并行向运营商请求 API 产品订单。运营商通过 TMF937 使用 API 产品使用 API 向聚合器报告 API 产品使用情况。
3. TMF Operate API：通用实现指南
3.1 同步与异步操作
TMF API 通常允许两种操作模式：同步和异步。同步操作在返回结果时完成，异步操作在接收请求后立即处理，并返回 202 Accepted 结果代码。
3.2 字符串格式和限制
大多数 TMF Operate API 中的字符串属性没有长度限制，可能导致互操作性问题。因此，文档中提供了一些指南，如 URL/URI 的最大长度为 2048 个字符，ID 的最大长度为 200 个字符等。
3.3 API 安全
TMF Operate API 应使用 OpenId Connect (OIDC) 作为 OAuth 2.0 的扩展进行 API 身份验证，并使用 client_credentials 作为 grant_type，使用 private_key_jwt 在 OAuth 2.0 流中进行授权。
3.4 API Web 通知安全
渠道合作伙伴可以通过 hub 端点操作或与运营商之间的手动协议来管理对通知的订阅。TMF Operate API 后端服务应使用 OAuth 2.0 身份验证和 client_credentials grant_type 以及 client private_key_jwt 授权方法向提供的回调端点发送通知。
3.5 HTTP X-Correlator 头
建议在 API 响应中包含可选的 x-correlator 头，以实现端到端可观察性。当 API 消费者包含非空的“x-correlator”头时，API 提供者必须在响应中包含相同的值。
3.6 HTTP 语言选择
API 客户端可以在 HTTP 请求中包含 Accept-Language 头，列出语言代码，API 将尝试匹配首选语言。API 响应消息可以回复 Content-Language 头，包含使用的语言代码。
4. TMF931 登出和订购 API 指南
4.1 TMF931 强制操作
列出了 TMF931 OAS 规范和互操作性指南中规定的强制操作，包括 ApiProduct、ApiProductOrder、Application 和 ApplicationOwner 的 GET 和 POST 操作。
4.2 TMF931 API 安全
TMF931 Operate API 应使用 OpenId Connect (OIDC) 进行身份验证，并使用 client_credentials 作为 grant_type，使用 private_key_jwt 在 OAuth 2.0 流中进行授权。
4.3 渠道合作伙伴登出流程
渠道合作伙伴和运营商资源假定由运营商在注册渠道合作伙伴为 TMF Operate API 消费者时创建。渠道合作伙伴应能够接收属于它们的资源登出 API 通知。
4.4 审批状态
TMF931 登出 API 引入了应用程序所有者和应用程序审批的概念，允许运营商异步验证应用程序所有者提供的数据。为了互操作性，如果父应用程序所有者或应用程序未获得批准，则应用程序和 ApiProductOrder 创建操作将被拒绝。
4.5 税号格式
engagedParty.taxNumber 属性的格式应按照以下规则进行验证：
- 默认情况下，如果不存在特定的本地指令，税号应以 DUNS 格式定义，为 9 位数字。
- 特定的本地指令基于运营商和国家（从 engagedParty.registeredGeographicalAddress.countryCode.value 获取）在表 6 中提供。
4.6 ApiProductOrder
ApiProductOrder 表示添加新产品或修改或删除现有产品的订单列表。因此，ApiProductOrder 可以由类型为 ApiProductOrderItemAdd、ApiProductOrderItemModify 或 ApiProductOrderItemDelete 的订单项列表组成。
4.7 事件订阅
虽然通知事件在 TMF931 Conformance Profile 中不是强制的，但对于互操作性，所有在 TMF931 登出 API 中定义的事件类型都是强制的。这意味着：
- POST /hub 和 DELETE /hub/ 操作是可选的，因为渠道合作伙伴和运营商也可以通过手动协议对通知事件的订阅细节进行协商。
- 任何 TMF931 登出 API 中定义的事件类型都可以用作 POST /hub 操作中的 eventType 过滤器。
4.8 Monitor
TMF931 登出 API 不限制 Monitor 状态的可能值。为了互操作性，应考虑以下值：
- InProgress
- InError
- Completed
4.9 完整登出和订购流程
渠道合作伙伴应使用以下流程进行完整应用程序登出：
- 如果应用程序所有者尚未创建，请使用 POST /applicationOwner 操作请求其创建。
- 使用 POST /application 操作创建应用程序。
- 使用 POST /apiProductOrder 创建 ApiProductOrders。
- 如果 ApiProductOrder 被认可，则当目标应用程序所有者和应用程序的 approvalStatus 值为批准时，ApiProductOrderItems 状态将进展到 inProgress 或 inProgress.accepted。当订单处理完成时，ApiProductOrder 状态将进展到 completed、partial 或 failed 状态。
4.10 PATCH 操作
虽然 PATCH 操作在 TMF931 Conformance Profile 中不是强制的，但它可以用于：
- 修复拒绝的应用程序所有者或应用程序创建请求
- 传达应用程序所有者或应用程序数据的更新
4.11 区域指南
4.11.1 巴西
- 税号应为新的字母数字 CNPJ（Cadastral Nacional da Pessoa Jurídica），由 14 个字母数字字符组成。
4.11.2 欧盟
- GDPR 定义了不同参与方在个人数据处理中的角色，因为义务和责任取决于这些角色。
- 欧盟 VAT 格式具有以下结构：
- 国家代码：两个字母
- 税号：取决于国家 EU 成员国和 EU 关联国家。
5. TMF936 产品目录 API 指南
TMF936 Open Gateway 产品目录 API 允许渠道合作伙伴检索运营商提供的 Open Gateway 提供商。
6. TMF937 产品使用 API 指南
TMF937 Open Gateway 产品使用 API 允许渠道合作伙伴检索应用程序的 Open Gateway 产品使用情况。
附录 A：示例
提供了与 TMF931 登出和订购 API Conformance Profile 和 OpenAPI 定义相关的示例，包括应用程序所有者、应用程序、ApiProductOrder 和 Hub 事件订阅的示例。
附录 B：文档管理
B.1 文档历史
记录了文档的历史版本和变更情况。
B.2 其他信息
提供了文档所有者和其他相关信息。
