云制造服務(wù)平臺(tái)開放接口要求

1云制造服務(wù)平臺(tái)開放接口要求本文件規(guī)定了云制造服務(wù)平臺(tái)的開放接口模型、接口類型與設(shè)計(jì)編寫要求。本文件適用于與云制造服務(wù)平臺(tái)的制造資源接入、微服務(wù)/APP開發(fā)應(yīng)用有關(guān)的接口開發(fā)、調(diào)用與測(cè)試。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對(duì)應(yīng)的版本適用于本文件；不注日期的引用文件，其最新版本（包括所有的修改單）適用于本文件。GB/T29826-2013云制造術(shù)語3術(shù)語與定義GB/T29826-2013界定的以及下列術(shù)語和定義適用于本文件。3.1開放接口openinterface云制造服務(wù)平臺(tái)提供的開放性應(yīng)用程序編程接口。3.2工業(yè)應(yīng)用服務(wù)接口industrialapplicationsserviceinterface在云制造服務(wù)平臺(tái)上，提供的支持工業(yè)應(yīng)用開發(fā)和管理等方面的開放接口。3.3制造資源/能力聯(lián)接接口manufacturingresources/capabilitiesconnectinginterface在云制造服務(wù)平臺(tái)上，為工業(yè)設(shè)備、工業(yè)服務(wù)、工業(yè)產(chǎn)品聯(lián)接到平臺(tái)，提供的支持?jǐn)?shù)據(jù)傳輸、資源管理、標(biāo)識(shí)等方面的開放接口。4縮略語下列縮略語適用于本文件。API：應(yīng)用程序編程接口（ApplicationProgrammingInterface）APP：應(yīng)用程序（Application）CAD：計(jì)算機(jī)輔助設(shè)計(jì)（ComputerAidedDesign）CAE：計(jì)算機(jī)輔助工程（ComputerAidedEngineering）CAM：計(jì)算機(jī)輔助制造（ComputerAidedManufacturing）CAPP：計(jì)算機(jī)輔助工藝過程設(shè)計(jì)（ComputerAidedProcessPlanning）DNC：分布式數(shù)控（DistributedNumericalControl）ERP：企業(yè)資源計(jì)劃（EnterpriseResourcePlanning）2EDI：電子數(shù)據(jù)交互（ElectronicDataInterchange）ID：身份標(biāo)識(shí)號(hào)（Identification）IT：信息技術(shù)（InformationTechnology）MES：生產(chǎn)制造過程執(zhí)行系統(tǒng)（ManufacturingExecutionSystem）PLM：產(chǎn)品生命周期管理（ProductLifecycleManagement）SaaS：軟件即服務(wù)（Software-as-a-Service）SDK：軟件開發(fā)工具包（SoftwareDevelopmentKit）WebService：Web服務(wù)（WorldWideWebService）HTTP：超文本傳輸協(xié)議（HypertextTransferProtocol）AMQP：提供統(tǒng)一消息服務(wù)的應(yīng)用層標(biāo)準(zhǔn)高級(jí)消息隊(duì)列協(xié)議（AdvancedMessageQueuingProtocol）MQTT：消息隊(duì)列遙測(cè)傳輸（MessageQueuingTelemetryTransport）SSL：安全套接層（SecureSocketLayer）TSL：傳輸層安全（TransportLayerSecurity）SLA：服務(wù)等級(jí)協(xié)議（service-levelagreement）OWASP：開放式Web應(yīng)用程序安全項(xiàng)目（OpenWebApplicationSecurityProject）5開放接口模型5.1概述云制造服務(wù)平臺(tái)開放接口模型架構(gòu)見圖1，包括工業(yè)應(yīng)用服務(wù)接口和制造資源/能力聯(lián)接接口兩大類開放接口。兩大類接口可使用HTTPS、MQTT等傳輸協(xié)議，宜遵守OpenAPISpecification、SLA、OWASP等規(guī)范。圖1開放接口模型5.2工業(yè)應(yīng)用服務(wù)接口3工業(yè)應(yīng)用服務(wù)接口分為工業(yè)應(yīng)用開發(fā)接口和工業(yè)應(yīng)用管理接口，其中工業(yè)應(yīng)用開發(fā)接口包括數(shù)據(jù)類接口、模型類接口和微服務(wù)類接口，應(yīng)明確工業(yè)應(yīng)用開發(fā)調(diào)用的數(shù)據(jù)、模型和微服務(wù)的接口；工業(yè)應(yīng)用管理接口應(yīng)包括應(yīng)用管理類接口和安全類接口，應(yīng)提供應(yīng)用部署、監(jiān)控管理、身份認(rèn)證、訪問控制、權(quán)限管理等方面的接口。5.3制造資源/能力聯(lián)接接口制造資源/能力聯(lián)接接口分為制造資源/能力聯(lián)接服務(wù)接口和制造資源/能力聯(lián)接管理接口，其中制造資源/能力聯(lián)接服務(wù)接口應(yīng)包括設(shè)備數(shù)據(jù)類接口、設(shè)備控制類接口、系統(tǒng)數(shù)據(jù)類接口和聯(lián)接安全類接口，應(yīng)明確工業(yè)設(shè)備、工業(yè)信息系統(tǒng)與平臺(tái)交互的接口和工業(yè)設(shè)備控制、保障聯(lián)接安全的接口；制造資源/能力聯(lián)接管理接口應(yīng)包括設(shè)備管理類接口、邊緣管理類接口和標(biāo)識(shí)類接口，提供工業(yè)設(shè)備、邊緣網(wǎng)關(guān)等邊緣資源管理和標(biāo)識(shí)的接口。6接口類型6.1概述云制造服務(wù)平臺(tái)開放接口主要有以下幾種類型：a）數(shù)據(jù)類；b）模型類；c）微服務(wù)類；d）安全類；e）標(biāo)識(shí)類；f）管理類；g）控制類。6.2工業(yè)應(yīng)用服務(wù)接口6.2.1數(shù)據(jù)類接口數(shù)據(jù)獲取接口應(yīng)用開發(fā)數(shù)據(jù)類接口應(yīng)包含數(shù)據(jù)獲取接口，數(shù)據(jù)獲取的典型接口定義見表1。表1數(shù)據(jù)獲取接口定義身份認(rèn)證唯一標(biāo)識(shí)（Stringapp_key）、身份認(rèn)證token（String數(shù)據(jù)分析接口應(yīng)用開發(fā)數(shù)據(jù)類接口應(yīng)包含數(shù)據(jù)分析接口，數(shù)據(jù)分析的典型接口定義見表2。4表2數(shù)據(jù)分析接口定義至少包含：企業(yè)ID（StringentId）、身份認(rèn)證唯一標(biāo)識(shí)（Stringapp_key）、身份認(rèn)證token（Stringacc6.2.2模型類接口模型注冊(cè)接口應(yīng)用開發(fā)模型類接口應(yīng)能實(shí)現(xiàn)模型注冊(cè)，模型注冊(cè)的典型接口定義見表3。表3模型注冊(cè)接口定義模型狀態(tài)查詢接口應(yīng)用開發(fā)模型類接口應(yīng)能實(shí)現(xiàn)業(yè)務(wù)流程、研發(fā)仿真、數(shù)據(jù)算法和行業(yè)機(jī)理等類型模型的狀態(tài)查詢、參數(shù)交互，模型狀態(tài)查詢的典型接口定義見表4。表4模型狀態(tài)查詢接口定義6.2.3微服務(wù)類接口微服務(wù)注冊(cè)接口應(yīng)用開發(fā)微服務(wù)類接口應(yīng)能實(shí)現(xiàn)平臺(tái)微服務(wù)的信息發(fā)布，微服務(wù)注冊(cè)的典型接口定義見表5。表5微服務(wù)注冊(cè)接口定義5微服務(wù)查詢接口應(yīng)用開發(fā)微服務(wù)類接口應(yīng)能實(shí)現(xiàn)平臺(tái)微服務(wù)的運(yùn)行狀態(tài)查詢，微服務(wù)查詢的典型接口定義見表6。表6微服務(wù)狀態(tài)查詢接口定義6.2.4應(yīng)用管理類接口應(yīng)用部署發(fā)布接口應(yīng)用管理類接口應(yīng)包含應(yīng)用部署發(fā)布接口，應(yīng)用部署發(fā)布的典型接口定義見表7。表7應(yīng)用部署發(fā)布接口定義應(yīng)用健康狀態(tài)監(jiān)測(cè)接口應(yīng)用管理類接口應(yīng)包含應(yīng)用監(jiān)控管理接口，應(yīng)用健康狀態(tài)監(jiān)測(cè)的典型接口定義見表8。表8應(yīng)用健康狀態(tài)監(jiān)測(cè)接口定義至少包含：應(yīng)用ID（StringappId）、發(fā)布應(yīng)用的用戶賬號(hào)（Stri6.2.5應(yīng)用安全類接口應(yīng)用安全類接口應(yīng)包含用戶身份認(rèn)證、獲取訪問權(quán)限等接口，典型接口定義見表9。表9應(yīng)用安全認(rèn)證接口定義6.3制造資源/能力聯(lián)接接口6.3.1設(shè)備數(shù)據(jù)類接口設(shè)備/產(chǎn)品狀態(tài)接口設(shè)備數(shù)據(jù)類接口主要包含設(shè)備/產(chǎn)品狀態(tài)接口，設(shè)備/產(chǎn)品狀態(tài)的典型接口定義見表10。表10設(shè)備/產(chǎn)品狀態(tài)接口定義設(shè)備/產(chǎn)品數(shù)據(jù)接口設(shè)備數(shù)據(jù)類接口主要包含設(shè)備/產(chǎn)品數(shù)據(jù)接口，設(shè)備/產(chǎn)品數(shù)據(jù)的典型接口定義見表11。表11應(yīng)用部署發(fā)布接口定義至少包含：網(wǎng)關(guān)ID（StringgatewId）、設(shè)備ID（Stringdev6.3.2設(shè)備控制類接口設(shè)備控制類接口用于設(shè)備/產(chǎn)品開關(guān)機(jī)、命令下發(fā)等，典型接口定義見表12。表12設(shè)備控制接口定義至少包含：設(shè)備ID（StringdevId）、指76.3.3系統(tǒng)數(shù)據(jù)類接口系統(tǒng)數(shù)據(jù)類接口應(yīng)包含ERP、MES、PLM等信息系統(tǒng)與平臺(tái)進(jìn)行交互的接口，典型接口定義見表13。表13生產(chǎn)物料表單保存接口定義6.3.4聯(lián)接安全類接口聯(lián)接安全類接口用于對(duì)設(shè)備身份進(jìn)行鑒權(quán)，典型接口定義見表14。表14設(shè)備安全認(rèn)證接口定義至少包含：設(shè)備ID（StringdevId）、設(shè)備6.3.5設(shè)備管理類接口設(shè)備管理類接口應(yīng)包含設(shè)備/產(chǎn)品的創(chuàng)建、分組、編輯、刪除、導(dǎo)入、導(dǎo)出和設(shè)備模板管理等接口，典型接口定義見表15。表15設(shè)備/產(chǎn)品查詢接口定義6.3.6邊緣管理類接口邊緣管理類接口應(yīng)包含邊緣網(wǎng)關(guān)、云邊協(xié)同、邊緣運(yùn)行環(huán)境管理等接口，典型接口定義見表16。表16邊緣網(wǎng)關(guān)創(chuàng)建接口定義至少包含：網(wǎng)關(guān)名稱（StringgatewName）、網(wǎng)關(guān)類型（String86.3.7標(biāo)識(shí)類接口設(shè)備/產(chǎn)品標(biāo)識(shí)保存接口標(biāo)識(shí)類接口應(yīng)包含設(shè)備/產(chǎn)品標(biāo)識(shí)接口，設(shè)備/產(chǎn)品標(biāo)識(shí)保存的典型接口定義見表17。表17設(shè)備/產(chǎn)品標(biāo)識(shí)保存接口定義網(wǎng)關(guān)標(biāo)識(shí)保存接口標(biāo)識(shí)類接口應(yīng)包含網(wǎng)關(guān)標(biāo)識(shí)接口，網(wǎng)關(guān)標(biāo)識(shí)保存的典型接口定義見表18。表18網(wǎng)關(guān)標(biāo)識(shí)保存接口定義7接口編寫要求7.1實(shí)用性編寫接口API應(yīng)符合以下實(shí)用性要求：a）數(shù)據(jù)格式：應(yīng)使用支持跨平臺(tái)、通用性的文件格式，例如JSON、ProtoBuf等，也可采用XML、TEXT作為程序開發(fā)輔助；b）接口執(zhí)行效率（接口訪問速度）：PHP推薦使用YAF框架，.NET推薦使用Newtonsoft；c）數(shù)據(jù)量：按需分配；d）API緩存：包括文件緩存及memcache緩存。7.2易用性編寫接口API應(yīng)符合以下易用性要求：a）接口、參數(shù)命名準(zhǔn)確：接口及參數(shù)應(yīng)包含必要內(nèi)容，易于理解；b）接口數(shù)據(jù)、狀態(tài)：對(duì)于傳輸成功/失敗的情況，接口必須提供明確的數(shù)據(jù)狀態(tài)信息及返回值；c）接口可擴(kuò)展性：接口應(yīng)具備可擴(kuò)展性，可支持功能調(diào)整或者擴(kuò)展。7.3安全性編寫接口API應(yīng)符合以下安全性要求：a）接口安全：應(yīng)使用約定的算法，對(duì)傳遞的參數(shù)值進(jìn)行驗(yàn)證匹配；b）加密規(guī)范：在傳遞用戶名密碼時(shí)，應(yīng)采用規(guī)范的加密算法，進(jìn)行數(shù)據(jù)通信請(qǐng)求，推薦使用國(guó)產(chǎn)加密算法；9c）接口版本控制：應(yīng)對(duì)接口進(jìn)行版本控制，平臺(tái)及軟硬件升級(jí)時(shí)更新接口版本，宜定期處理新、舊版本接口的狀態(tài)。8接口設(shè)計(jì)要求8.1一般要求接口設(shè)計(jì)應(yīng)盡量減少參數(shù)傳遞，按請(qǐng)求情況進(jìn)行傳遞。接口設(shè)計(jì)應(yīng)盡量避免接口重復(fù)性，提高接口復(fù)用性，減少HTTP請(qǐng)求，提高程序穩(wěn)定性。8.2數(shù)據(jù)類型規(guī)范設(shè)計(jì)接口時(shí)，應(yīng)標(biāo)注參數(shù)數(shù)據(jù)類型，以及是否可為空或者默認(rèn)字段，設(shè)計(jì)參數(shù)數(shù)據(jù)類型應(yīng)與對(duì)應(yīng)返回?cái)?shù)據(jù)類型一致，參數(shù)字段不匹配容易造成APP程序出現(xiàn)數(shù)據(jù)類型解析異常。8.3編碼規(guī)范接口開發(fā)過程中，應(yīng)標(biāo)注接口編碼方式，宜采用UTF-8編碼。8.4請(qǐng)求方式編寫接口時(shí)應(yīng)標(biāo)注請(qǐng)求方式，一般有GET和POST方式。在數(shù)量較小情況下使用GET方式，數(shù)據(jù)量超過1024字節(jié)時(shí)應(yīng)采用POST方式，避免出現(xiàn)請(qǐng)求失敗或者請(qǐng)求異常的問題。8.5返回接口調(diào)用狀態(tài)所有API接口都應(yīng)使用統(tǒng)一的調(diào)用成功/失敗標(biāo)識(shí)信息和錯(cuò)誤編碼信息，以及必要的提示字段信息。8.6安全機(jī)制設(shè)計(jì)接口應(yīng)使用驗(yàn)證簽名機(jī)制，可支持接口安全驗(yàn)證。8.7參數(shù)說明接口應(yīng)標(biāo)注參數(shù)名稱、是否必選、數(shù)據(jù)類型及范圍、說明以及“否（必選）”傳遞默認(rèn)的參數(shù)。9接口注冊(cè)要求推薦使用HTTPS協(xié)議（基于TCP/IP），使用POST和GET方式提交數(shù)據(jù)，以及MQTT協(xié)議。接口定義遵循RFC1945（HTTP1.0）、RFC2616（HTTP1.1RFC0959（FTPRFC1866（HTMLRFC4627（JSON）。10接口調(diào)用要求接口調(diào)用應(yīng)進(jìn)行身份核實(shí)，使用規(guī)范的接口調(diào)用方法，同時(shí)應(yīng)記錄接口調(diào)用信息，可正確解析接口調(diào)用的反饋結(jié)果。11數(shù)據(jù)包格式11.1參數(shù)11.1.1平臺(tái)系統(tǒng)級(jí)參數(shù)平臺(tái)系統(tǒng)級(jí)參數(shù)見表19?？刹捎脩?yīng)用授權(quán)認(rèn)證接口方式，接口開發(fā)時(shí)必須申請(qǐng)應(yīng)用分配api_key和參數(shù)簽名密鑰api_secret。表19API系統(tǒng)級(jí)參數(shù)參數(shù)名類型是否必需描述api_keystring是注冊(cè)應(yīng)用時(shí)分配到的api_keymethodstring是采取相應(yīng)命名空間方式制定方法名call_iduint是時(shí)間戳，同一個(gè)應(yīng)用的不同API請(qǐng)求的time值應(yīng)該是遞增的formatstring否響應(yīng)包格式，可采用XML或JSONstring否API調(diào)用請(qǐng)求包的編碼類型，可采用UTF-8和GBKbd_sigstring是參數(shù)簽名，應(yīng)實(shí)現(xiàn)bd_sig外所有參數(shù)串的簽名，包括業(yè)務(wù)級(jí)的參數(shù)。11.1.2業(yè)務(wù)級(jí)參數(shù)的通用約定業(yè)務(wù)級(jí)參數(shù)的通用約定見表20。表20業(yè)務(wù)級(jí)參數(shù)參數(shù)名類型描述page_noInt用于支持分頁的API，表示第幾頁，默認(rèn)為1page_sizeInt用于支持分頁的API，表示每頁返回多少條數(shù)據(jù)，默認(rèn)以及上限為25device_typeInt終端類型11.2響應(yīng)數(shù)據(jù)包格式規(guī)范11.2.1XML輸出格式XML輸出格式應(yīng)采用文檔編碼格式UTF-8。接口的返回?cái)?shù)據(jù)中，數(shù)組對(duì)應(yīng)的XML節(jié)點(diǎn)應(yīng)包含list=”true”屬性，其子節(jié)點(diǎn)的標(biāo)簽名應(yīng)跟對(duì)應(yīng)的數(shù)據(jù)有聯(lián)系，并且同個(gè)數(shù)組內(nèi)的同級(jí)節(jié)點(diǎn)的標(biāo)簽名應(yīng)一致；對(duì)象類型和普通數(shù)據(jù)類型數(shù)據(jù)（如string，int，double，bool）對(duì)應(yīng)的XML節(jié)點(diǎn)不包含list屬性或者list屬性值為false，節(jié)點(diǎn)標(biāo)簽名應(yīng)具有實(shí)際意義，并與數(shù)據(jù)所描述的信息相符。11.2.2JSON輸出格式接口傳遞format參數(shù)為JSON格式時(shí)，正常響應(yīng)包應(yīng)符合以下要求：字符串編碼格式是UTF-8，字符串內(nèi)容是XML輸出數(shù)據(jù)所對(duì)應(yīng)的PHP數(shù)組的標(biāo)準(zhǔn)JSON字符串。11.3錯(cuò)誤響應(yīng)輸出格式錯(cuò)誤響應(yīng)輸出內(nèi)容應(yīng)符合以下規(guī)范：a)返回內(nèi)容應(yīng)由error_code，error_msg，request_args3個(gè)屬性組成，分別用于描述錯(cuò)誤碼，錯(cuò)誤信息，以及調(diào)用API時(shí)傳遞的所有參數(shù)的信息；b)request_args屬性應(yīng)為一個(gè)數(shù)組，由n個(gè)包含key和value屬性的對(duì)象組成；c)JSON格式的字符串內(nèi)容是XML輸出數(shù)據(jù)所對(duì)應(yīng)的PHP數(shù)組的標(biāo)準(zhǔn)JSON字符串。11.4錯(cuò)誤碼定義接口