Translated message

A translation of this page exists in English.

Red Hat Entitlement Gateway:Vendor API 开发人员指南

已更新 -

关于本指南

本指南详细介绍了如何通过服务帐户与 Red Hat Entitlement Gateway Vendor API 集成，并提供了处理通过 ISV 频道的最终用户订单的流程信息。

您或您所在机构应已与红帽的合作伙伴集成团队联系，以获取这些 API 的访问权限。

联系红帽合作伙伴集成开发团队

请联系您所在机构中与红帽合作伙伴集成团队进行联系的部门，以获取专门的 slack 频道链接。

如果在集成过程中或集成完成后出现与 Red Hat Entitlement Gateway Vendor API 相关的问题，请通过 slack 频道联系我们，这是联系合作伙伴集成团队的最快方法。

Vendor API 的 Open API 规格

Red Hat Entitlement Gateway 提供了多个 API，但并非所有 API 都与供应商集成相关，请使用 “Vendor 类过滤 API。请为 preprod 或 production 调用正确的 Entitlement Gateway 实例来发送订单数据。

Pre-Production:Stage 环境

https://entitlement-gateway.stage.api.redhat.com/swagger-ui/index.html?urls.primaryName=Vendor

生产（Production）环境

https://entitlement-gateway.api.redhat.com/swagger-ui/index.html?urls.primaryName=Vendor

先决条件

在开始 API 集成前，请确保：

  1. 存在一个 Red Hat Organization Account ("Corporate") 帐户，可用于请求 Red Hat IAM 帐户。
  2. 在前一步中从 Red Hat Organization Account 请求的两个 Red Hat SSO IAM 服务账户，一个用于 preproduction 环境，一个用于生产（production）环境。API 以后在进行 OAuth 时需要使用这些服务帐户。
  3. 完成了获得访问 Red Hat Vendor API 的过程并确认可以成功进行访问。

使用 JWT 令牌访问 Vendor API

请注意，Authorization 标头中的 应替换为来自上一请求的属性 access_token 的 bearer 令牌

显示 https 请求中的授权标头格式的示例

curl --location 'https://entitlement-gateway.api.redhat.com/v1/...' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <valid-access-token>'
  • 结果令牌 access_token 是一个 JWT，它在 15 分钟后过期 (900 秒)
  • 在调用服务来进行验证和授权时，可以在请求 Authorization 标头中使用这个临时令牌

与 Vendor Orders API 集成

在验证了授权流后，下一步是与 vendor orders API 集成。请参阅 OpenAPI 规格

V1 API 规格（已弃用）

为一个示例请求/响应创建 Vendor Order API。

V2 API 规格（新版！）

要测试订单创建，请使用 Stage 环境 entitlement-gateway.stage.api.redhat.com

当成功创建订单时，API 会为每个订单返回唯一的链接。在为最终用户提供这个订单链接时，供应商应以安全的方式进行。客户需要点此链接来完成订单连接。

订购连接链接示例 https://console.redhat.com/connect/vendor/vendor-name/5ce74cc0-a341-4538-b8e9-de83521fd706

Red Hat Customer Guide 包括了与客户共享的详细信息，详细描述了连接一个订单的步骤。请共享此文章以及订单确认。

附录

先决条件：请求一个新的红帽机构帐户（Red Hat Organization Account）

请根据 Red Hat Account Management FAQ 中的说明进行操作

备注：
在创建新帐户时，请选择帐户类型 "Corporate"。

现有客户：
如果已有现有的合作伙伴机构帐户（Partner Organization Account），可以选择重复使用此帐户。但是，许多团队都会选择继续请求新的机构管理员帐户来限制特定团队或事业部的服务帐户访问权限。

先决条件：请求 Red Hat SSO IAM 服务帐户

Red Hat Vendor API 使用 OAuth 2.0 规格，需要创建 sso.redhat.com 的服务帐户。

要在生产环境中集成 Vendor API，建议在请求新的红帽帐户时选择 "Corporate" 类型，以便稍后请求服务帐户。 "Corporate" 帐户允许"机构管理员"来管理服务帐户和安全凭证的所有权。

备注：请求机构帐户是一个一次性的设置，其他集成可以重复使用相同的帐户

Red Hat API 集成最佳实践是，建议在 preprod 环境和生产环境中分别使用独立的帐户凭证。
应向红帽提供两个服务帐户，以允许授权 API 访问：

  • 与 Stage 环境集成的服务帐户
  • 与生产环境集成的服务帐户

参考信息
https://docs.redhat.com/en/documentation/red_hat_customer_portal/1/html/creating_and_managing_service_accounts/ref-ciam-svc-acct-api-creating-service-acct

Red Hat Account Management FAQ

  1. 创建新的机构帐户：https://access.redhat.com/articles/customer-service-accounts#createlogin
  2. 检查帐户是否为个人或是公司帐户 ：https://access.redhat.com/articles/customer-service-accounts#Check
  3. 常规帐户管理问题：https://access.redhat.com/articles/customer-service-accounts

先决条件：访问 Red Hat Vendor API

请通过电子邮件为 Red Hat Partner Integration 团队提供 Red Hat SSO 服务帐户的详细信息，包括 staging 和 production 服务帐户的名称和 client ID。Partner Integration 会一起处理针对 preproduction 和 production 的权限请求，为双方节省时间以完成集成。

电子邮件模板示例

Subject:
Requesting access to Red Hat's vendor APIs

Body:
I am requesting access via service account to Red Hat's vendor APIs.

Stage service account information:
- service account name: <your service account name here>
- client ID: <your client ID here>

Prod service account information:
- service account name: <your service account name here>
- client ID: <your client ID here>

API 集成：故障排除和常见问题

问题 #1：使用访问令牌访问 API 时出现 HTTP 403 状态

如果是第一次与 Red Hat Vendor API 集成，请在使用凭证前请求对 Red Hat vendor API 的 preprod 和 production 服务账户的授权访问。请参阅请求访问 Red Hat Vendor API 一节

问题 #2:无法访问 console.stage.redhat.com

console.stage.redhat.com 只能通过红帽内部网络访问。如果从外部网络访问，则会显示 "Preprod lockdown:Access denied”.如果需要在 preprod 中进行端点到端点的验证，Red Hat Partner Integration 团队可帮助进行订单激活。

问题 #3:其他问题

如果需要向 Red Hat Partner Integration 团队报告问题，请使用我们的 slack 频道，或使用正常的红帽支持联系方式。

术语表

供应商（Vendor）
"ISV"或"Independent software vendor， 独立软件供应商"。这是指销售红帽软件/产品的外部机构或合作伙伴。在此工作流中，供应商与红帽合作为客户置备权利。

客户（Customer）
在其机构中的一个或多个红帽产品用户。

订单（Customer）
从供应商处购买的红帽产品。它包括一个或多个红帽权利。每个权利包括一个或多个产品。一个完整的订单会链接到一个红帽帐户

权利（Entitlement）
购买的产品和/或功能列表，包括 SKU 和数量信息。为每个权利创建一个红帽订阅。

产品（Product）
在授权中包括的单行项目或 SKU + 数量。在一个权利中，每个 SKU 必须是唯一的

Comments