YD_T 4422-2023 基于表述性状态转移 (REST)技术的业务能力开放应用程序接口 (API)邮件业务.docx

《YD_T 4422-2023 基于表述性状态转移 (REST)技术的业务能力开放应用程序接口 (API)邮件业务.docx》由会员分享，可在线阅读，更多相关《YD_T 4422-2023 基于表述性状态转移 (REST)技术的业务能力开放应用程序接口 (API)邮件业务.docx（89页珍藏版）》请在课桌文档上搜索。

1、1.u335.U5uCCSM21.YD中华人民共和国通信行业标准YD/T44222023基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）邮件业务RESTfu1.basedservicecapabi1.ityopenAPIEmai1.2023-11-01实施2023-07-28发布中华人民共和国工业和信息化部发布前言II1范围12规范性引用文件13术语、定义和缩略语13.1 术语和定义13.2 缩略语24邮件业务概述25邮件业务AP1.定义35.1 概述35.2 资源概述353数据类型76资源详细定义136.1 通用要求1362用户接口1363标魏口276.4 草稿接口34

2、6.5 邮件夹接口46.6 附件接口5267电子白W1.转口577安全要求817.1 认证和授权817.2 AP1.访问权限和频率控制82附录A（规范性）响应码要求83本文件按照GBn.1-2020标准化工作导则第1部分：标准化文件的结构和起草规则？的规定起草.清注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的击任.本文件由中国通信标准化协会提出和归口。本文件起草单位：西安交通大学、中国电信柒团有限公司。本文件主要起草人：曲桦、赵李红、李金艳、吴彤、杨峰义、张彦鹏、边江、刘伟、张斌.基于表述性状态转移(REST)的业务能力开放应用程序接口(APD邮件业务1本文件现定r明于表述

3、性状态转移(REST)技术实现邮件业务的开放应用程序接口(APD,包括接口的资源定义、资源操作、数据结构和安全要求等。本文件适用于提供怖件业务能力开放的应用程序接口(API)的研发、测试.2捉范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款.其中,注日期的引用文件,仅该日期对应的版本适用于本文件；不注口期的引用文件，其最新版本(包括所有的修改单适用本文件。YD2144-2010基于简单邮件传输协议(SMTP)的互联网中文电子眦件地址技术要求YD/T2423-2012恭于表述性状态转移(REST)技术的电信业务能力开放平台技术要求IETFRFC26I6传输控制协议(Hy

4、peneXtTranSferProtoco1.HTTP/1.I)IETFRFC3986统一资源标识符(URI):三11Ji(UniformResourceIdcntificrtURIxGcncricSyntax)IETFRFC4627JavaScript对象标记(json)的app1.icat沁MjSOII媒体类型Theapp1.ication/jsonMediaTypeforJavaScriptObjectNotation(JSON)3术语、定义和3.1术语和定义下列术语和定义适用于本文件。3.1.1表述性状态转移representationa1.statetransfer一种针对网络应用的

5、设计和开发方式,指的是一组架构的束条件和原则,可以降低开发的复杂性.提高系统的可伸缩性.来源：YEKT242320123.1.2电子库件emai1.在计算机网络上，用户终端之间往来的信函，来源：YD.T2144-20103.1.3IK名单b1.acknane记录发送坨圾邮件的服务器的IP或者主机信息的名单。来滁：YDTB1.1.-20043.2下列缩玷语适用于木标准。PI应用程序编程接口App1.icationProgrammingInterfaceAuth4AP1.网络应用程序接口授权框架AuthorizaticHiFrameworktorNCIwortiAPIsIrrM1.超文本标记语音H

6、ypertextMarkup1.anguageHTTP超文本传输协议HyperTextTransferPro(OCo1.IP因特网协议InierneiProioco!JSONJaYaSCriP1.对象表示法JavaScriptObjectNotationMIME多功能网络邮件扩展MuhipurposeInternetMai1.ExtensionsOMA开放移动联盟OpenMobi1.eA1.1.ianceREST表述性状态粘移RcprcscnUitiofUiIStatetransferSMTP简单邮件传输协议Simp1.eMai1.TransferProtoco1.URI统一资源标识Unifo

7、rmResourceIdcn1.iHcrUR1.统一资源定位符UniformResource1.ocatorXM1.扩展标记语言extensib1.eMarkupImnguagcXSDXM1.模式定义XM1.SchemaDefinition4部件业务就电子邮件(EmaiI)业务是指两个用户终端通过计算机网络交换电子邮件的一种服务。该业务为，对多服务,即每个邮件发送方可对应一个或多个加件接收用户.邮件业务具有一下业芬特征：一支持获取用户信息、更新用户信息、获取通讯录、添加通iR录、移出通讯录获取黑名单、添加黑名单、移出黑名单：一支持创建标签、获取标签、获取标釜列衣、删除标签、更新标签：支持创电草

8、稿、获取草犒、获取草稿列表、删除草稿、更新草稿：支持创建邮件夹、获取幅件夹、获取邮件夹列表、删除邮件夹、更新邮件夹：支持获取觇件附件、获取邮件附件列表、班除邮件附件：一支持创建邮件、发送I件、获取邮件、获取胭件列表、删除邮件、批量删除邮件、更新邮件、修改邮件标签、批后修改邮件标签、移动邮件、批或移动邮件：_本标准以邮件基本业务为主,并选取邮件业务中其他常见和重要功能，编写邮件业务能力开放接口.随着眺件业务发展，所包含的业务功能可适时扩充.5事件业务AP庞义5.1本堂介绍门拈件业务AP1.的设计，它详细的介绍f所有资源的定义，所有数据结构的定义，所有指定资源的详细操作定义.5.2 资源雌本节简要

9、概括了关于邮件业务的REST风格AP1.中所用到的所有资源.本标准中UR1.变量“apiVcrsion”的取值为P”，表明AP1.对应于本标准,UR1.变量“apiVcron”的语义定义见OMAOMA-TS-REST_Nc1.AP1.Common-V1_0.图1可视化地展示了邮件业务API中定义的资源树结构图,资滁树中那些与本标准中定义的HTrP方法关联的节点用固体盒子（实体源）描述。T48荷g-Tg-QMBbck1.i乂Oj*rcmveBIW.istInOMetami1.DJujui1.一bu1.chDekuEmM1.k一豆)Tii1.chMoJifyEniaikOI-aEE10件业务的资叫

10、构卜面的表格给出了才:标准中定义的资源的概述，其数据类型表示和允许的HrrP方法.表I对由6件基础业务进行了具体的描述，包括创建扰件、发送邮件、获取邮件、茯取胭件列表、州除邮件、批法蒯除吃件、更新幅件、修改邮件标签、批量修改邮件标签、移动帆件、批量移动邮件等功能，井对其资源的详细说明、数据结构以及允许的HTTP方法做了假述。1郎钳a务资源R1.BesdiR1.zhttzsrrvcrRt)/InpiVrrxicn1.数据结构KE方法GCTPvrPOSTDE1.I11E创建既件Awi1.sBtai1.否否运网创建成功的配件伯恩否发送部件4rdi1.ssenrRoot)iVersiJ数据结构HTTP

11、方法GCTPVTFXXSDE1.ETE获取如件列明coci1.sEnai1.s返I可航件列表SSS删除每件dtei1.skSS返回成功刷除的消息批制射除邮件roniIs/batchDe1.eteEiwi1.sEnai1.ids否S返问成功删除的潸息更於MSftw*i1.s(xi1.1.dEiMii1.Sjg回的个抵件否修改邮件标签/z*xmi1.snaiI1.d1.ZirKidifyEnai1.1.abe1.1.ds否否运问隼个如件否批修改邮件标签ciIsZbBtchNodifyEBaiUIiiwi1.s1.abe1.1.ds古S返网修改成功的消息S移动HJtt/tii1.s/Aiai11df

12、feEaa11Eiwi1.否否返回他个部件否批出带动邮件r11Mi1.xbatchMav1.ntInEnai1.1.dsEnai1.s古否通回邮件列货否表2对昵件用户相关业务进行了具体的描述，包括获取用户信息、更新用户信息、获取通讯录、添加通讯录、移出通讯录、获取黑名单、添加黑名单、移出黑名单等功能.并对其资源的详细说明、数据结构以及允许的HrrP方法做了概述.2施件殳务用户资源VK.Biid.W.:Mtp:/(servejot)/piVorsin)数据结构HTTP方法CTPVTPOSTDE1.ETE获取用户信息/userBnai!Account返Ew1.户信息任更新用户信息/userEnai

13、!Account台返回用户伯息否狭取通讯量/user/conucisContacts返回联东人列表SSS添加通讯承sercontacuadCtftctsContacts看否返E联东人列表S移出血讯录uscrcoatacts.,rrxcCntactx台於返回联系人列裹否秩取累名电Zuxor/b1.ack1.istB1.ark1.i5;t返日非名城否否否添m黑石软/user/bIack1.istZeddB1.ack1.istB1.ack1.isi否否返阿非名於否2部件业务用户（Ir资源IR1.Base1.iR1.:http:/serverRxc1.apiVersion】数据站构HTTP方法GCTI

14、1.1.TPOSTDHIErE移出加名单/user/b1.ack1.ist/rcnwB)ack1.istB1.ack1.istSS返F1.非名外否表3对邮件标签进行了具体的描述，包括创建标签、获取标签、获取标卷列表、刑除标签、更新标签等功能，并对其资源的详细说明、数据结构以及允许的H1.TP方法做极述，3部件标签资源UR1.BasetR1.:http:serverRooi)/jIVers1.oi1.数据结构HTTP方法GCTPVrPC67DEirTE创建标提/1.abe1.s1.obe)否.,返回创建成功的的患有获取板笠1.be1.8(1.abeJId1.1.abe1.返网第个标笠古否否度双标

15、茶利衣/1.abe1.sMbcU退标茶列&否fiJK朦标卷/1.abe1.s/(1.abcHd1.S,苦返网制除成功的消息更新板笠AabdMkbeud1.1.abe1.SJS回电个If法SS表4对邮件草稿进行了具体的描述,包括创建草稿、获取草稿、获取草稿列表、删除草稿、更新草稿等功能，并对其资源的详细说明、数据结构以及允许的HTTP方法做概述，4部件草槁资源IRI.BasctR1.:http:/serrcrRt)/IzpiVrrsionI数据1.HTTP方法CCTPtaPwDE1.ETE创建草稿/draftsDrafttifi返回创建成功的铀息i获取9fft/drafts/!draftId)D

16、raft迈向单个草稿S否否法取以信列&,draftsDrafts返回国事列出否不涮除点播/drafts/(draftId)否S返回成功出除的消JB型新草稿/drafts/(draftId)Draftfi诋回羊个草核fi表5对部件业务的邮件夹进行了具体的描述，包括创建邮件夹、获取邮件夹、获取瞅件夹列表、刑除邮件央、更新邮件夹等功能，并对其资源的详细说明、数据结构和允许的HTrP方法做了极述，5部件堡务峰件夹资淞1.R1.BasctR1.:M:/senrRoot/IapiVerstcnf结构HTTP方法CFTpt11POSTMaKIE创建用件夹/fo1.dersFo1.derS否这回创出成功的消息

17、S获取国件夹/fo1.ders/(fo1.der1.Fo1.der返品单个tt:件失否SS获取够件关列表/fo1.dersFa1.dcrs返日帆件夹列大否HiJMBfSC件夹/fo1.ders/(fo1.der1.dtf台这向成功H除的沛息更新邮件夹fo1.dcrsIfo1.dorId!Fo1.der否返回用件*ni8Attachnents返回薛件附件列衣否否S制除体件附件atachuens(atiachfxntId)否SS返回成功删除的俯息5.3岫知5.3.1 XM1.命名空间邮件业务RESTfU1.API数据类型XM1.命名空间是：um:oma:xm1.:res1.:ne(api:emai

18、1.:I本标准中以“x$d”为命名前例的数据类型引用了W3CXM1.Schema1.WSCXM1.SChema2中定义的XM1.数据类型，“common”命名空间前缀引用了OMAOMA-TS-REST_Ne1.AP1.CommOn中定义的数据类型,命名前微的使用，例如，xsd并没有语义上的重要性.5.3.2&a21侬本H对邮件业务RESTfU1.网络AP1.中使用的数据结构进行了定义.YD/T442220235322931.bai1.EmiaI数据结构的定义见表7,*7Eaia1.f1.MM元案类曼站诲J0汽描述EHindxs;d：3；tring必选施件般一且不可受标IR符PamnFo1.de

19、rIdxsd：8tring必选机件的父俄件夹的或一MiM符freeEirei1.Account(I).un1.xundei必逢发件人集合toEsniIAccount0.UnbOundcd必选收件人典介subjectXddistring必选M件主题dateXsdzdateTiBe必逢部件生成或更新的时间sizeXKdzpnxitireInternri部件火小.以字1.为单位ie(rtanceI(xrtani可透邮件的猿要性1.abe1.s1.ebeIf,unboundedqi够件标签bohPrevie*xs;d：3；tring赭件正文中的陋255个字苻作为出件笫妥bodyxsd:string部件

20、正文atIachftHitAtIachientA一个具彳旧】血1数据类型的emai1.根元索允许出现在通知请求和/或响应的消息体中.512.3皿Baai1.sEmiak数据结构的定义见表8.8元素类型必选/可选描述Ctiai1.sES1.diI0.unbounded0选IW件集合Omi1.CountXsdzinUger必选邮件集合大小5.3.249ffiBni1.1.dsEmiaIk1.S数据结构的定义见表9。9EBiandS数据靖构元激类型必选/可选描述idsxsd:string0.unbounded必造邮件唯一标风存集令CnaI】IdC(XJn1.rsd:1.nteeexaffp1.e.c

21、onaccountNameXKdzxtring必选抵件用户呢称（例如.张三）一个具有EmiaIACCoUm数据类型的emia1.Accom根元素允许出现在通知响应的消息体中。5.326ffi:ContactsComac1.s数据结构的定义见表I1.三11CtactsWM构元激类型0选/可选描述accounts1.itiIACCoUnt0.Un1.X1.Undrd必造修件用户集合accountTotaiXSdrinueer必选通讯及长度一个具有COntaCtS数据类（的COntaCtS根元素允许出现在通知响应的消息体中。5.32.7料1B1.ack1.istBIack1.i$t数据结构的定义见表

22、12。12B1.aCk1.iSt则醐聃元激炎型必出可逡描述accountsEEihcc11unt0.unbnu11dcd必选WrR名注的pc件用户次合aceountouixsrnft0.unhrundnd心选草箱集合draftCountXadUnteeer必选小稿象会大小一个具有DraftS数据类型的dmf1.s根元素允许出现在通知响应的消息体中.5.3213类型tAttachmentAUaChment数据结构的定义见表18。18AttachaentftftttK11*类禁必选/可选描述att1.dxsd:string必透附件唯标识符MtNanQXsdrstring必选附件的攵件名typexs

23、d:string可选MDa,用於表示附件类型.恒EIFRFC6838中进行了定义和标准化sizeXxdzpositivc1.ntrgcr可选附件大小.以字节为单位dataXsdzstring必地用UR1.和文件幺安全字传Gf时称为-Wb-Safe”成-baseMuri”）编码的坎充的、basc61编码的字节市.由RFC4648定义的一个具有Attachment据类型的auachnen根元索允许出现在通知响应的消息体中。5.3214AttachmentsAuaChmen1.S数据结构的定义见表19。19Attac1.eents则构元案类型。选何选描述a1.tsAttachmentO.unboun

24、ded必送附件集令MtCountxxd:integer必选附件家仆大小一yt*具有AUaehmenIS数据类型的at1.achmemsR元素允许出现在通知响应的消息体中。5.3.2.15如1.Fo1.derFO1.dCr数据结构的定义见表20,20Fo1.derMttM元素类型必逸，可地靖述fo1.der1.dxsd:string1Z部件夹堆一标出符enai1.1.dsxsd:stringO.unbounded必选电件曜一标双符集合fo1.derXanrxsd:string0选第件夹名称tota1.IiefiCountxsd:integer可选配件夹内IW件总SireadCountxsd:in

25、teger可选肥件夹内已读那件数UnrcadCountxsd:integernr能件夹内未该部件数typeTyPC0透HH1.火的所有并类型.用户林件夹由用户倒也.用户可以作以和删除.系统能件夹是系统内部创建的,不能率加、悔改和JM除一个具有Fo1.der数据类型的f。Ider根元素允许出现在:通知响应的消息体中.5.3.216料1Fb1.dersFb1.ders数据结构的定义见表21.*21Fo1.dersRIittK元素类51必选/可选描述fo1.ders;Fo1.der0.unbounded!必选帆件火集合fo1.d*rCuntxsd:integer必选帆件夹笑含大小一个具有FOidCE

26、数据类里的fk1.C3报元素允许出现在通知响应的消息体中.&a217题IpeTyPe数据结构的定义见表22。22Type敷握靖构枚举依描述SYSTEM系统类型USER用户自定义类型5.3.2.18ICI里蛆合消息的我示在邮件业务AP1.中，附件的上传马获取操作可以在HTrP请求中包含文件内容，此类具有多个实体的消息体的MIME采用Fiu1.tipartnrmdata格式，其中,第一个实体将包含数据根元隶，笫二个实体包括多媒体内容.Fiu1.1.ipartbmFdata格式的消息体结构的详细定义见OMAOMA-TS-REST.NctAP1.Common-V1_06资源曲航义6.1通用戛求下列规定

27、对本标准定义的资源都适用，而和资源的表示格式无关(即XM1.、JSON.app1.ication.1x-www-fo11n-ur1.encoded):遵循IETFRFC3986规定，UR1.变m(即UR1.中花括号“”中的参数)中的保宙字符应是采用百分号编码(例如“%3B”编码表示“：”)，该要求对请求行中的请求UR1.和消息体中的资源表示(例如“1.ink”元素中的“rcsourccUR1.”)都适用。如果一个anyUR1.类型的用户标识是MS1.SDN形式，该用户标识应为IETFRFC3966定义的全球号码(例如.tt服务器1.*1.:生机名称+靖口+基础路径.珀口和基础路柱为可选。例如,

28、http:/ex.mpk.CWexuikPI23请求UR1.变量（K名称说明npiVrrxion.客户岔里使用的AP1.版本，其取依见第5.2节的定义userid航件业务用户使用的唯地址.由RFC822指定格式的加件地1匕例如.account!w三p1.e.ccaUR1.变用的保傍字符见笫6.1节的定义。6.2.1.3HTTP晌应码见OMAoMA-TS*RE5T_NCtAP1.Commen-Vu)的定义及附录A所列举部分.621.4GET该操作被用作莪取用户估息.示例1:获取用户佶息请求GET/examp1.eAPI/emaWv1.，accounUeNamp1.e.coiwuserHTTP.I

29、.IACCCPt:app1.ication，jsonHost:c.xamp)响应返何的资源数据是EmMACSUrH类型的数据,即岷件用户信恩HTTPU1.200OKDate:Mon,05Apri1.202110:30:05GMTContcnt-TypczappIicationZjsonContenb1.engthznnnn(emai1.Account:(accoiinhddress:account1.e.xam|),aixoun1.Name:张三)6.2.1.5 PUT该资源不允许使用本方法，返回的HTrP错误状态是遵循IETFRFC26I6第M.7节，服务器在响应时还应包括,A1.1.owG

30、ET.POST,字段。6.2.1.6 POST该资糠不允许使用本方法，返回的HTrP错误状态是405。遵循IETFRFC26I6第M.7节，服务器在晌应时还应包括“A1.1.ow:GET,POST字段,6.2.1.7 DE1.ETE该资源不允许使用本方法，返回的HrrP错误状态是405。遵循IETFRFC26I6第14.7节，服务器在响应时还应包括“A1.1.ow:GET.POST字段.6.2.1.8 户值总的Ma2.2.1侬更新用户信息的资源是：hupy(ServerRoot/emai1./(apiVersion/serk1.user该资源表示更新郎件用户的基本信息.6.2.2.2 调求UR

31、1.度量请求UR1.变Kt描述见表2九*24请求UR1.变名称说明j4rverRc米务褂IR1.:主机名称端口,茶础路径.筑口和范础路径为可选.例如，htpexa11p1.e.ccmexaw1.eAPIapiVcrsion客户带型使用的AH版木，或取伤见第5.2%的定义userid1件业务用户使用的唯一地址，由RFC822指定格式的够件地址。例如.acxm1.XaweXHiip12CdmUR1.变值的保留字符见第6.1节的定义。6.2.2.3HTTPU向应码见OMAOMA-TS-REST_Nei,P1.COmmOn-V1_0的定义及附录A所列举部分,6.2.2.4 GET该资源不允许使用本方法

32、，返回的I1.TTP错误状态是105,遵循IETFRFC2616第14.7节，服务器在响应时还应包括“A1.1.ow:GErPOST字段.6.2.2.5 PUT该操作被用作更新用户信息.示例1：更新用户信息请求请求UR1.参数见表25。25更新用户值JM悚UR1.ft元案类型必出可选描述:%ccountXmmsd:String必选班件用户呢梆(例如,张三)PUTexamp1.cAPIemai1.v1.account1.(exanp1.c.uomuserHTTP/1.1Accept:app1.ica(ionjsonH(accouniName:李四响应返M1.的资源数据足Emai1.ACCOUnt

33、类型的数据,即邮售用户信息.HTTP1.I2OKDa1.e:MOn.05Apri1.202110:30:05GMTContent-Type:app1.icatkn/jsonContent-1.engthmnnn(emai1.Accouni”:accountAddress:accountICXamPI,accountNamc:李四”16.2.2.6 POST该资源不允许使用本方法.返回的HTrP错误状态是405.遵循IETFRFC2616第14.7节.，服务器在响应时还应包括*1.1.owGET.POS,字段。6.2.2.7 DE1.ETE该资源不允i午使用本方法，返回的IrrTP错误状态是40

34、5.遵循IETPRFC2616第14.7节，服务器在宿应时还应包括“A1.1.ow：GETTOST字段。6.2.2.8 WRf1.mft&2&1获取用户通讯录的资源是：http(ScrverRiHM)/emai1.(apiVersion,useriduser)11tacts该资源表示获取用户通讯来的基本信息.6.2.3.2请求UR1.变量请求UR1.变同描述见表26。26请求UR1.交，名称说明serverRt很务器UR1.:主机名称，刑口，基即路径.端口和双岫路径为可选“例如，httpxi11jIe.coexa11pkPIapiVersion客户希望使用的API坂本，共取价见冷5.2节的定义userid邮件业务用户使用的唯一地址，由RFc822指定格式的邮件地址。例如,JtCCGUnINax111e.xxtUR1.变量的保留字符见第6.1节的定义.1.1.1.1HTn应码见OMAOVA-TS-REsT_NCtAP1.CommOn-V1.O的定义及附录A所列举部分.1.1.1.4 GET该操作被用作获取用户通讯录。示例1:骁取用户通讯录请求GETcxamp1.cAPICmaiIAWaccount1CXamPIC.comusContaCtSH11P1.Izccept:app1.ica1.ion(jsonHoscex