版本 2023.10.20.001
版權與專有資訊聲明
© 2023 Synopsys, Inc. 本新思科技 Cloud OpenLink 應用程式介面 (API) 及其所有相關文件均為 Synopsys, Inc. 之專有財產,僅得根據與 Synopsys, Inc. 簽訂之書面協議條款與條件進行使用。
免責聲明
Synopsys, Inc. 及其授權人對本資料不作任何明示或暗示的擔保,包括但不限於對適銷性及特定用途適用性的暗示擔保。
商標
新思科技及特定新思科技產品名稱為新思科技的商標,詳見 https://www.synopsys.com/company/legal/trademarks-brands.html。所有其他產品或公司名稱可能是其各自所有者的商標。
第三方連結
本文件中包含的任何第三方網站連結僅為方便您使用而提供。新思科技對此類網站及其實務(包括隱私權實務、可用性與內容)不予背書,亦不負任何責任。
本文件說明新思科技 Cloud OpenLink API,該介面可讓半導體晶圓廠、EDA 及 IP 供應商在系統層級與新思科技 Cloud 進行互通。具體而言,供應商可以提供其針對新思科技 Cloud 客戶的產品授權資訊。客戶可以使用該 API 向供應商請求授權,隨後這些授權將安裝至新思科技 Cloud 中。 本文件的範圍涵蓋以下新思科技 Cloud OpenLink API 功能:
新思科技 Cloud 客戶 導覽至新思科技 Cloud 入口網站 UI 中的「第三方授權」頁面客戶 選擇一個 供應商 以便瀏覽授權並最終請求授權Synopsys Cloud 透過以下項目擷取客戶的可用授權 供應商 授權 API 端點供應商 API 回應會列出由 UI 呈現的可用授權客戶 選擇要請求授權的授權數量並提交請求Synopsys Cloud 呼叫 供應商 授權 API 端點供應商 回應並提供安裝於 Synopsys Cloud 授權伺服器上的授權檔案
此處的圖表說明了授權流程。
本節中的序列圖顯示了以下流程的基本概念。
用於與新思科技 Cloud 進行整合的 API 係採用 OpenAPI v3 標準進行規格制定。該規格包含實作 API 所需的所有詳細資料。本節提供其他資訊以釐清規格內容。
本節提供新思科技 Cloud OpenLink API 的常見屬性。
TLS 2.0 或更高版本透過 https 進行。Content-Type: application/json 支援用於請求。OAUTH2 以及 API 金鑰支援基於的驗證。各供應商透過手動佈署流程向「新思科技雲端」註冊授權 API。用於在供應商端識別客戶的特定客戶詳細資料會經過協議,並儲存於「新思科技雲端」中供客戶使用。
下表總結了佈署所需的資訊類型。
| 屬性 | 選項 |
|---|---|
| 供應商的驗證方法 | API 金鑰或 OAuth 2 |
| 供應商的驗證 API | 網址、參數、標頭 |
| 供應商的授權查詢 API | 網址、參數、標頭 |
| 供應商的客戶識別 | 必填欄位清單 |
供應商 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
}
...
]
}
上述必填參數中指定的數值隨後會提供於屬性 vendorCustomerIdentification 下方,並與權利及授權金鑰擷取的 API 請求一併發送。
權利 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" }
}
對於根據 RFC 6749 進行的雙足 (two-legged) OAuth2.0 驗證, 供應商 需要驗證 URL、用戶端 ID 和用戶端密鑰才能進行 API 啟用。您可以透過其他靜態參數來擴充這些參數,這些參數將合併至 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 客戶 要求授權。
客戶位於新思科技雲端(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 至供應商授權產生端點。
在 UI 中設定請求的數量後, 供應商 用於請求授權的端點會從 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,以便在供應商於回應中指定的時間後下載授權檔案。 若授權檔案的佈建無法在 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 表示新思科技應何時嘗試下載,並使用 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 (透過 NodeJS) 針對新思科技® 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}`)
})