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

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 草稿接口346.5 邮件夹接口46.6 附件接口5267电子白W1.转口577安全要求817.1 认证和授权817.2 AP1.访问权限和频率控制82附录A（规范性）响应码要求83本文件按照GBn.1-2020£标准化工作导则第1部分：标准化文件的结构和起草规则？的规定起草.清注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的击任.本文件由中国通信标准化协会提出和归口。本文件起草单位：西安交通大学、中国电信柒团有限公司。本文件主要起草人：曲桦、赵李红、李金艳、吴彤、杨峰义、张彦鹏、边江、刘伟、张斌.基于表述性状态转移(REST)的业务能力开放应用程序接口(APD邮件业务1本文件现定r明于表述性状态转移(REST)技术实现邮件业务的开放应用程序接口(APD,包括接口的资源定义、资源操作、数据结构和安全要求等。本文件适用于提供怖件业务能力开放的应用程序接口(API)的研发、测试.2捉范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款.其中,注日期的引用文件,仅该日期对应的版本适用于本文件；不注口期的引用文件，其最新版本(包括所有的修改单适用本文件。YD"2144-2010基于简单邮件传输协议(SMTP)的互联网中文电子眦件地址技术要求YD/T2423-2012恭于表述性状态转移(REST)技术的电信业务能力开放平台技术要求IETFRFC26I6传输控制协议(HypeneXtTranSferProtoco1.HTTP/1.I)IETFRFC3986统一资源标识符(URI):三11Ji(UniformResourceIdcntificrtURIxGcncricSyntax)IETFRFC4627JavaScript对象标记(json)的app1.icat沁MjSOII媒体类型Theapp1.ication/jsonMediaTypeforJavaScriptObjectNotation(JSON)3术语、定义和3.1术语和定义下列术语和定义适用于本文件。3.1.1表述性状态转移representationa1.statetransfer一种针对网络应用的设计和开发方式,指的是一组架构的束条件和原则,可以降低开发的复杂性.提高系统的可伸缩性.来源：YEKT242320123.1.2电子库件emai1.在计算机网络上，用户终端之间往来的信函，来源：YD.T2144-20103.1.3IK名单b1.acknane记录发送坨圾邮件的服务器的IP或者主机信息的名单。来滁：YDTB1.1.-20043.2下列缩玷语适用于木标准。PI应用程序编程接口App1.icationProgrammingInterfaceAuth4AP1.网络应用程序接口授权框架AuthorizaticHiFrameworktorNCIwortiAPIsIrrM1.超文本标记语音HypertextMarkup1.anguageHTTP超文本传输协议HyperTextTransferPro(OCo1.IP因特网协议InierneiProioco!JSONJaYaSCriP1.对象表示法JavaScriptObjectNotationMIME多功能网络邮件扩展MuhipurposeInternetMai1.ExtensionsOMA开放移动联盟OpenMobi1.eA1.1.ianceREST表述性状态粘移RcprcscnUitiofUiIStatetransferSMTP简单邮件传输协议Simp1.eMai1.TransferProtoco1.URI统一资源标识UniformResourceIdcn1.iHcrUR1.统一资源定位符UniformResource1.ocatorXM1.扩展标记语言extensib1.eMarkupImnguagcXSDXM1.模式定义XM1.SchemaDefinition4部件业务就电子邮件(EmaiI)业务是指两个用户终端通过计算机网络交换电子邮件的一种服务。该业务为，对多服务,即每个邮件发送方可对应一个或多个加件接收用户.邮件业务具有一下业芬特征：一支持获取用户信息、更新用户信息、获取通讯录、添加通iR录、移出通讯录'获取黑名单、添加黑名单、移出黑名单：一支持创建标签、获取标签、获取标釜列衣、删除标签、更新标签：支持创电草稿、获取草犒、获取草稿列表、删除草稿、更新草稿：支持创建邮件夹、获取幅件夹、获取邮件夹列表、删除邮件夹、更新邮件夹：支持获取觇件附件、获取邮件附件列表、班除邮件附件：一支持创建邮件、发送I®件、获取邮件、获取胭件列表、删除邮件、批量删除邮件、更新邮件、修改邮件标签、批后修改邮件标签、移动邮件、批或移动邮件：_本标准以邮件基本业务为主,并选取邮件业务中其他常见和重要功能，编写邮件业务能力开放接口.随着眺件业务发展，所包含的业务功能可适时扩充.5事件业务AP庞义5.1本堂介绍门拈件业务AP1.的设计，它详细的介绍f所有资源的定义，所有数据结构的定义，所有指定资源的详细操作定义.5.2 资源雌本节简要概括了关于邮件业务的REST风格AP1.中所用到的所有资源.本标准中UR1.变量“apiVcrsion”的取值为P”，表明AP1.对应于本标准,UR1.变量“apiVcron”的语义定义见OMAOMA-TS-REST_Nc1.AP1.Common-V1_0.图1可视化地展示了邮件业务API中定义的资源树结构图,资滁树中那些与本标准中定义的HTrP方法关联的节点用固体盒子（实体源）描述。T48荷g¾-Tg-Q"MBbck1.i乂Oj*rcmveBIW.istInOMetami1.DJujui1.一"bu1.chDekuEmM1.k一豆)Tii1.chMoJifyEniaikOI-aEE10件业务的资叫构卜面的表格给出了才:标准中定义的资源的概述，其数据类型表示和允许的HrrP方法.表I对由6件基础业务进行了具体的描述，包括创建扰件、发送邮件、获取邮件、茯取胭件列表、州除邮件、批法蒯除吃件、更新幅件、修改邮件标签、批量修改邮件标签、移动帆件、批量移动邮件等功能，井对其资源的详细说明、数据结构以及允许的HTTP方法做了假述。«1郎钳a务资源R1.BesdiR1.zhttz<srrvcrR<x>t)/InpiVrrxicn1.数据结构KE方法GCTPvrPOSTDE1.I11E创建既件Awi1.sBtai1.否否运网创建成功的配件伯恩否发送部件<4rdi1.ssen<1.Eai1.Iurei1否否返回接受那件Jft送谛求泪息S获取部件ZeiRii1.sZUwi1.1.d)Ghai1.返问单个邮件SSS«1事件开破业务OK)资源UR1.Baso1.W.:hitp:/n>rRoot)iVersiJ数据结构HTTP方法GCTPVTFXXSDE1.ETE获取如件列明coci1.sEnai1.s返I可航件列表SSS删除每件dtei1.sk<tei1.1.d>SS返回成功刷除的消息批制射除邮件roniIs/batchDe1.eteEiwi1.sEnai1.ids否S返问成功删除的潸息更於MSftw*i1.s(xi1.1.dEiMii1.Sjg回的个抵件否'修改邮件标签/z*xmi1.snaiI1.d1.ZirKidifyEnai1.1.abe1.1.ds否否运问隼个如件否批修改邮件标签c>iIsZbBtchNodifyEBaiUIiiwi1.s1.abe1.1.ds古S返网修改成功的消息S移动HJtt/«tii1.s/Aiai11dff>eEaa11Eiwi1.否否返回他个部件否批出带动邮件r11Mi1.xbatchMav<1.ntInEnai1.1.dsEnai1.s古否通回邮件列货否表2对昵件用户相关业务进行了具体的描述，包括获取用户信息、更新用户信息、获取通讯录、添加通讯录、移出通讯录、获取黑名单、添加黑名单、移出黑名单等功能.并对其资源的详细说明、数据结构以及允许的HrrP方法做了概述.«2施件殳务用户资源VK.Biid.W.:Mtp:/(servejot)/piVorsi<>n)数据结构HTTP方法CTPVTPOSTDE1.ETE获取用户信息/userBnai!Account返Ew1.户信息任更新用户信息/userEnai!Account台返回用户伯息«否狭取通讯量/user/conucisContacts返回联东人列表SSS添加通讯承sercontacuadCtftctsContacts看否返E联东人列表S移出血讯录uscrcoatacts.,rrx>cCntactx台於返回联系人列裹否秩取累名电Zuxor/b1.ack1.istB1.ark1.i5;t返日非名城否否否添m黑石软/user/bIack1.istZeddB1.ack1.istB1.ack1.isi否否返阿非名於否»2部件业务用户（Ir资源IR1.Base1.iR1.:http:/s>erverRxc"1.apiVersion】数据站构HTTP方法GCTI1.1.TPOSTDHIErE移出加名单/user/b1.ack1.ist/rcnw¢B)ack1.istB1.ack1.istSS返F1.非名外否表3对邮件标签进行了具体的描述，包括创建标签、获取标签、获取标卷列表、刑除标签、更新标签等功能，并对其资源的详细说明、数据结构以及允许的H1.TP方法做极述，«3部件标签资源