新思科技
Ansys

新思科技 Cloud OpenLink API 規格說明文件

README.md

版本 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 中的授權檔案,供特定客戶使用

高階流程

  • A 新思科技 Cloud 客戶 導覽至新思科技 Cloud 入口網站 UI 中的「第三方授權」頁面
  • 該 客戶 選擇一個 供應商 以便瀏覽授權並最終請求授權
  • Synopsys Cloud 透過以下項目擷取客戶的可用授權 供應商 授權 API 端點
  • 該 供應商 API 回應會列出由 UI 呈現的可用授權
  • 該 客戶 選擇要請求授權的授權數量並提交請求
  • Synopsys Cloud 呼叫 供應商 授權 API 端點
  • 該 供應商 回應並提供安裝於 Synopsys Cloud 授權伺服器上的授權檔案

 

新思科技 Cloud OpenLink API 規格 (.yaml)

README.md

此處的圖表說明了授權流程。

本節中的序列圖顯示了以下流程的基本概念。

  • 基於 OAUTH2 的驗證(支援 OAUTH2 與 API 金鑰)
  • 檢索授權權益
  • 設定授權請求
  • 請求授權


用於與新思科技 Cloud 進行整合的 API 係採用 OpenAPI v3 標準進行規格制定。該規格包含實作 API 所需的所有詳細資料。本節提供其他資訊以釐清規格內容。

  • 您可以使用線上 Swagger Editor 工具來檢視規格
  • 線上 Swagger Editor 工具亦可用於作為雲端服務,以任何程式語言(NodeJs、Java、Python、Ruby 等)自動產生可運作的參考伺服器及/或用戶端

本節提供新思科技 Cloud OpenLink API 的常見屬性。

  • 僅支援透過 https 進行的安全資料傳輸,且需使用 TLS 2.0 或更高版本透過 https 進行。
  • 僅 Content-Type: application/json 支援用於請求。
  • OAUTH2 以及 API 金鑰支援基於的驗證。
  • 使用者介面絕不會直接從客戶端裝置向供應商發出請求。所有針對供應商端點的請求皆源自於新思科技雲端服務層中受安全保護的定義網路。
  • 使用者介面絕不會擷取任何供應商 API 資訊。所有供應商 API 資訊(例如 URL、驗證方法、驗證 URL 以及 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

權利 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 金鑰的驗證, 供應商 必須為 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 進行的雙足 (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

授權 API 允許 Synopsys Cloud 從 供應商 為特定的 客戶.

廠商授權 API - 請求

將自 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 接入過程中。

供應商授權 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" }, }, } ] }

每個授權項目必須包含以下內容:

  • A 標題
  • 選填的 描述,最大可用數量 qtyMax,授權期限結束日期 termEndDate
  • 選填的任何輔助資訊,用於在該屬性下識別授權與授權請求 aux.

對於授權請求, 標題 以及 aux 物件與請求的數量一同提供 qtyMax 至供應商授權產生端點。

供應商授權請求 API

在 UI 中設定請求的數量後, 供應商 用於請求授權的端點會從 Synopsys Cloud被叫用。作為對請求的回應, 供應商 會提供所請求的授權或傳回錯誤。

  • 如果需要, 供應商 可以傳送多個授權檔案。每個授權檔案都可以透過 Synopsys Cloud 同步或非同步(輪詢)的方式從 供應商.
  • 如果授權產生時間少於 20 秒,應使用同步回應方法
  • 如果授權產生時間超過 20 秒,應使用非同步回應方法

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 陣列可包含其他錯誤資訊 (例如針對個別參數的特定錯誤)。

範例實作 (Node.js)

下列程式碼展示了使用 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}`) })

Ask BETA This experience is in beta mode. Please double check responses for accuracy.

結束聊天

關閉此視窗將清除您的聊天紀錄並結束本次會話。您是否確定要結束這次聊天? ```