版本 2023.10.20.001
版权与专有信息声明
© 2023 Synopsys, Inc. 本 Synopsys Cloud OpenLink 应用程序编程接口 (API) 及所有相关文档均为 Synopsys, Inc. 的专有财产,仅可根据与 Synopsys, Inc. 签订的书面协议的条款和条件进行使用。
免责声明
Synopsys, Inc. 及其许可方对本资料不作任何明示或暗示的保证,包括但不限于对适销性及特定用途适用性的暗示保证。
商标
Synopsys 以及某些 Synopsys 产品名称是 Synopsys 的商标,详见 https://www.synopsys.com/company/legal/trademarks-brands.html。所有其他产品或公司名称可能是其各自所有者的商标。
第三方链接
本文档中包含的任何第三方网站链接仅为方便您使用而提供。Synopsys 不对该等网站及其做法(包括隐私做法、可用性和内容)背书,也不承担任何责任。
本文档描述了 Synopsys Cloud OpenLink API,该 API 使半导体代工厂以及 EDA 和 IP 供应商能够与 Synopsys Cloud 进行系统级互操作。具体而言,供应商可以提供有关其针对 Synopsys Cloud 客户的产品授权的信息。客户可以使用该 API 向供应商请求许可证。然后,这些许可证将安装在 Synopsys Cloud 中。 本文档的范围涵盖以下 Synopsys Cloud OpenLink API 功能:
Synopsys Cloud 客户 导航至 Synopsys Cloud 门户 UI 中的“第三方授权”页面客户 选择一个 供应商 以便浏览授权并最终请求许可证Synopsys Cloud 通过以下方式获取客户的可用授权 供应商 授权 API 端点供应商 API 响应列出了由 UI 展示的可用授权客户 选择要请求许可证的授权数量并提交请求Synopsys Cloud 调用 供应商 许可证 API 端点供应商 作为响应,提供安装在以下设备上的许可证文件: Synopsys Cloud 许可证服务器
此处图示说明了许可证发放流程。
本节中的时序图展示了以下流程的基本原理。
用于与 Synopsys Cloud 集成的 API 采用 OpenAPI v3 标准进行规范。该规范包含实现 API 所需的所有详细信息。本节提供其他信息以阐明该规范。
本节介绍 Synopsys Cloud OpenLink API 的常见属性。
TLS 2.0 或更高版本 https 。支持Content-Type: application/json 用于请求。OAuth2 和 API 密钥支持基于该机制的身份验证。每个供应商通过手动入驻流程向 Synopsys Cloud 注册授权 API。用于在供应商端识别客户的特定客户详细信息需经过协商并在 Synopsys Cloud 中为该客户进行存储。
下表总结了入驻所需的信息类型。
| 属性 | 选项 |
|---|---|
| 供应商身份验证方法 | API 密钥或 OAuth 2 |
| 供应商身份验证 API | URL、参数、标头 |
| 供应商授权查询 API | URL、参数、标头 |
| 供应商客户标识 | 必填字段列表 |
供应商 API 入驻信息根据以下架构进行注册。为简便起见,本节进一步讨论的信息通过以下内容进行封装: <>
请参阅 Swagger OpenAPI 规范以了解
VendorApiRegistration
{
"auth":"OAUTH2",
"oAuthApi":<vendorAuthApi>,
"entitlementApi":<vendorEntitlementApi>,
"customerIdentification":{
"params":<vendorCustomerFields>
}
}
许可证生成的 API 端点由授权查询结果动态提供。这允许 供应商 针对不同的许可证提供不同的端点。
以下各节提供了有关 供应商 中注册的信息的具体属性的更多详细信息 Synopsys Cloud
但是 客户 将能够通过 供应商 被识别 D-U-N-S (企业专属的九位数标识符)号码。此外, 供应商 可以指定由 客户 被识别 Synopsys Cloud 向供应商提供的附加参数。
在接入 VendorApiRegistration 架构中,客户标识属性 customerIdentification 允许 vendor`` 用于定义可选的客户字段,这些字段将在从 Synopsys Cloud到vendor`。
请参阅 Swagger OpenAPI 规范以了解
VendorCustomerInfo
以下是可选客户字段的一个示例。在此例中,供应商要求客户提供一个字符串类型的必填参数 siteId.
...
"customerIdentification":{
"params":[
{
"title":"Site Id",
"key":"siteId",
"type":"String",
"required":true
}
...
]
}
上述必填参数中指定的值随后将与权益和许可证检索的 API 请求一起包含在属性 vendorCustomerIdentification 中提供。
权益 API 是一个静态 URL,需要在接入期间提供。用于检索许可证的进一步 API 信息则通过权益 API 动态提供。
{
"url": "https://api.vendor.com/v1/synopsys/get-entitlements",
"header": {
"my-extra-info":"anything"
},
"staticbody": {
"my-extra-info":"anything"
}
}
在 staticBody 下定义的属性将合并到权益 POST 请求的主体中。
对于基于 API 密钥的认证, 供应商 必须为 API 密钥提供标头和值
请参阅 Swagger OpenAPI 规范以了解
ApiKeyAuthInfo
以下是所需的接入信息示例: ApiKeyAuthInfo 所示如下:
{
"header":"x-api-key",
"value":"9114dd77-912e-4179-a8c5-0a8de9dd44cc"
}
但是 Synopsys Cloud 启动服务时,在对授权 API 和许可证生成 API 的每个请求中,都会在标头中提供 API 密钥,如下例所示:
{
"headers": { "x-api-key":"9114dd77-912e-4179-a8c5-0a8de9dd44cc" }
}
对于遵循以下标准的双向 OAuth2.0 身份验证 RFC 6749 进行 API 接入时,需要提供 供应商 提供的身份验证 URL、客户端 ID 和客户端密钥。可以使用其他静态参数扩充这些参数,这些静态参数将合并到 POST 请求正文中。
请参阅 Swagger OpenAPI 规范以了解
Oauth2ClientInfo
以下是所需的接入信息示例: Oauth2ClientInfo 此处显示为:
{
"url": "https://vendor.com/api/oauth2/token",
"header": {
"x-my-header": "xyz"
},
"staticBody": {
"origin": "synopsys"
},
"clientId": "6779ef20e75817b79602",
"clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
}
授权 API 允许 Synopsys Cloud 从 供应商 检索特定 客户.
将向 Synopsys Cloud 发送 POST 请求,并使用编码为正文参数的以下值:
SWAGGER:请参阅 Swagger OpenAPI 规范了解
EntitlementsRequestDto:
{
"customer": {
"name": "Big Chip Semi",
"dunsNumber": "1232234345",
"synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
"vendorCustomerIdentification":{
"sideId": "32668"
}
}
}
此信息由 供应商 用于识别 客户- vendorCustomerIdentification 属性在 Synopsys Cloud 供应商 API 接入过程中注册。
一旦从 Synopsys Cloud,权益 API 需遵循以下架构进行响应:
SWAGGER:请参阅 OpenAPI Swagger 规范获取
EntitlementsResponse
{
"customer": { }, // Same as in the request dto
"provides":[ ] // Array with entitlement information, See under "Item Type" for possible values
}
数组可能包含的内容详情 提供 将在 下一节中进行说明。如果所有许可证均可由来自 供应商的同一端点提供,则该数组可能仅包含一个条目。每个条目列出了可通过单个许可证检索端点获取其许可证的所有权益。如果需要不同的端点,则可以提供多个具有不同端点配置的项目。
此项目类型由 供应商 用于公开所有许可证权益并允许 Synopsys Cloud 客户 请求许可证。
客户的许可证服务器上。供应商供应商 在后续的许可证检索端点中以同步或异步方式提供。SWAGGER:请参阅 OpenAPI Swagger 规范获取
LicenseEntitlements
此处显示了作为 LicenseEntitlements 数组一部分的 EntitlementsResponse 提供 项目的示例。
{
"customer": {
"name": "Big Chip Semi",
"dunsNumber": "1232234345",
"synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
"vendorCustomerIdentification":{
"sideId": "32668"
}
},
"provides": [
{
"title": "AutoChip EDA Tools",
"description": "Digital Design EDA Tools Licenses",
"kind": "ProvideLicense",
"licenseEntitlements": [
{
"title": "Power Analyzer",
"aux":{"part": "part-1234"},
"qtyMax":10,
"termEndDate": "2024-08-01T00:00:00.000Z"
},
{
"title": "Timing Analyzer",
"aux":{"part": "part-5678"},
"qtyMax":5,
"termEndDate": "2025-08-01T00:00:00.000Z"
}
],
"licenseRequestApi":{
"url": "localhost:2000/get-license",
"header": {
"x-my-header": "xyz"
},
"staticBody": {
"origin": "synopsys"
},
},
}
]
}
每个权益项目必须包含以下内容:
标题描述,最大可用数量 qtyMax,许可期限的结束日期 termEndDateaux.对于许可请求, 标题 和 aux 对象将与请求的数量一同提供 qtyMax 给厂商许可生成端点。
在用户界面中配置请求的数量后, 供应商 请求许可的端点将从 Synopsys Cloud中调用。作为对该请求的响应, 供应商 将提供请求的许可或返回错误。
供应商 可以发送多个许可文件。每个许可文件都可以通过 Synopsys Cloud 同步或异步(轮询)方式提供回 供应商.SWAGGER:请参阅 OpenAPI Swagger 规范获取 ProvideLicenseRequestDto
此处提供了一个从 ProvideLicenseRequestDto 请求许可的 供应商 项示例:
{
"customer": {
"name": "Big Chip Semi",
"dunsNumber": "1232234345",
"synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
"vendorCustomerIdentification":{
"sideId": "32668"
}
},
"licenseRequests": [
{
"title": "Power Analyzer",
"aux":{"part": "part-1234"},
"qty": 2
},
{
"title": "Timing Analyzer",
"aux":{"part": "part-5678"},
"qty": 3
}
],
"host": {
"id": "id-auto-filled-by-snps",
"name": "auto-filled-by-snps"
},
"origin": "synopsys",
}
许可证请求端点的响应可以通过两种方式提供许可证文件:作为响应的一部分同步提供,或通过轮询下载 URL 异步提供。
SWAGGER:请参阅 Swagger 类型
ProvideLicenseResponse
同步响应直接将许可证文件作为 HTTP POST 响应正文的一部分返回。 如果许可证文件能够在 20 秒内完成配置,则会采用此响应类型,从而避免 HTTP 超时。
同步响应由属性 downloadType 设置为 "Sync" 来指示,该属性位于有效负载中。属性 数据 可用于容纳相关数据以及 filename 和一个或多个许可证的类型。对于许可证,属性 fileType 必须设置为 "License" ,如下方示例所示:
{
"files": [
{
"fileName": "lic_vendor_tool.lic",
"fileType": "License",
"data": "<Buffer 48 61 6c 6c 6f>",
"downloadType": "Sync"
}
]
}
文件属性 数据 包含 Base64 以缓冲区形式编码的许可证文件。请参阅下方使用原生 JavaScript 进行 Base64 编码的示例
const licenseString = 'SERVER enterp ...';
const buff = new Buffer(licenseString);
const data = buff.toString('base64');
异步响应不会直接将许可证文件作为 HTTP POST 响应的一部分返回。
相反,响应会提供一个 URL,用户可以在供应商在响应中指定的时间之后从该 URL 下载许可证文件。 如果许可证文件的配置无法在 20 秒内完成,则应使用此响应类型以防止 HTTP 超时。下图阐释了交互模型:
异步响应由属性指示 fileType 设置为 “Async” 在数组中 数据,对于每个许可证,都会给出许可证文件的下载说明(而不是许可证文件数据),如示例所示。
{
"files": [
{
"fileType": "Async",
"fileName": "lic_vendor_tool.lic",
"downloadType": "License",
"downloadApi":{
"url": "http://vendor.com/download?uuid=eec85dab-6de8-4f1f-8234-6df676bdb834",
"headers": {
"x-my-header": "xyz"
},
"staticBody": {
"origin": "synopsys"
},
"pollStartDateTime": "2023-07-12T09:40:18.000Z",
"pollIntervalSec": 30
}
}
]
}
属性 url 提供下载 URL 以及方法、可选的 headers,以及位于 staticBody之下的可选正文参数。ISO 日期字符串属性 pollStartDateTime 指示 Synopsys 应何时尝试下载,并使用 pollIntervalSec建议轮询间隔。如果文件尚不可用,则返回 404 响应。
如果作为 REST API 输入的参数验证失败,每个端点都应返回带有状态码 400 的错误,如下所示:
{
"code": "LICGEN001",
"message": "License generation failed",
"statusCode": 400,
"tid": "eec85dab-6de8-4f1f-8234-6df676bdb834",
"errors": [
{
"message": "LmHostId is missing but required"
}
]
}
属性 code 允许对供应商特定的错误代码进行编码。 message 包含有关要返回给 客户的错误的信息。可选属性 tid 允许插入 供应商 服务器跟踪 ID,用于跟踪和调试。这对于 500 内部服务器错误尤其有用。可选的 errors 数组可以包含附加的错误信息(例如,针对单个参数的具体错误)。
以下代码展示了使用 JavaScript (Node.js) 实现 Synopsys® Cloud OpenLink API 规范的一个简单且功能完备的示例。
/**
* NodeJS example application of the Synopsys® Cloud OpenLink API Specification
*
* npm install express
* npm install body-parser
* node main.js
*
*/
const express = require('express')
const bodyParser = require('body-parser')
const app = express()
/*
* Server settings
*/
const port = 2000
const host = 'localhost'
const protocol='http'
app.use(bodyParser.json())
// Some tracing...
app.use((req,res,next)=>{
console.log(`TRACE: ${req.method} ${req.url}`)
next();
})
/**
* Example implementation for get-license API
*/
app.use('/vendor-api/get-license', async (req, res) => {
// Vendor sample endpoint to generate a license with synchronous response
console.log(req.body)
const customer = req.body.customer
const hostId = req.body.host.id;
const hostName = req.body.host.name;
let response = {
files: []
}
const backOfficeLicenseGeneration=async ()=>{
return "DUMMY LICENSE FILE...."
}
/* Here, we generate a license per part as one possible option */
for (let licenseRequest of req.body.licenseRequests) {
/* Vendor's backoffice call to generate license*/
const licenseFile = await backOfficeLicenseGeneration(customer, hostName, hostId, licenseRequest.qty, licenseRequest.expiry, licenseRequest.aux.part)
response.files.push({
files: [{
fileType: "Sync",
data: Buffer.from(licenseFile, 'base64'),
fileName: `lic ${hostId}.txt`,
downloadType: "License"
}
]
})
}
/* Respond to Synopsys with generated licenses */
res.json(response)
})
/**
* Example implementation for get-entitlements API
*/
app.post('/vendor-api/get-entitlements', (req, res) => {
/* Vendor sample endpoint to query entitlements and map user options to vendor's get-license API spec */
const response = {
"customer": req.body?.customer,
"provides": [
{
"title": "AutoChip EDA Tools",
"description": "Digital Design EDA Tools Licenses",
"kind": "ProvideLicense",
"licenseEntitlements": [
{
"title": "Power Analyzer",
"aux":{"part": "part-1234"},
"qtyMax":10,
"termEndDate": "2024-08-01T00:00:00.000Z"
},
{
"title": "Timing Analyzer",
"aux":{"part": "part-5678"},
"qtyMax":5,
"termEndDate": "2025-08-01T00:00:00.000Z"
}
],
"licenseRequestApi":{
"url":`${protocol}://${host}:${port}/vendor-api/get-license`,
"header": {
"x-my-header": "xyz"
},
"staticBody": {
"origin": "synopsys"
},
},
}
]
}
res.json(response)
})
app.listen(port, () => {
console.log(`Example Synopsys® Cloud OpenLink API vendor server listening on port ${port}`)
})