YD/T 3102-2016.RESTful based service capability open API-customer profile (OMA-TS-REST _NetAPI_CustomerProfile-Vl_0，RESTful Network API for Customer Profile V1.0，NEQ).
1范围
YD/T 3102规定了基于表述性状态转移(REST)技术的用户信息业务开放应用程序接口(API)，包括接口的资源定义、资源操作、数据结构、基本流程和安全要求等。
YD/T 3102适用于提供用户信息业务能力开放的应用程序接口(API) 。
2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注8期的引用文件,仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。
OMA-TS-REST Common-V1_ 0-20120724-A RESTful网络API通用定义( Common definitions for RESTful Network APIs)
OMA-SUP-XSD_ _rest_ _netapi customerprofile-V1_ 0-20130305-C 用户信息RESTful网络API XML结
构(XML schema for the RESTful Network API for Customer Profile )
OMA-ER-Autho4API-V1_ 0-20131120-C 网络API授 权架构(Authorization Framework for Network
APIs)
W3C XMLSchemal可扩展标识语言架构第1部分:结构(第二版) (XML Schema Part 1: Structures Second Edition )
W3C XMLSchema2可扩展标识语言架构第2部分:数据类型(第二版) (XML Schema Part 2:Datatypes Second Edition)
3术语、定义和缩略语
3.1 术语和定义
下列术语和定义适用于本文件。

ICS33.030
中华人民共和国通信行业标准
YD/T3102-2016
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）用户信息业务
RESTfulbasedservicecapabilityopenAPcustomerprofileOMA-TS-REST NetAPI CustomerProfile-V1 O, RESTfulNetworkAPIforCustomerProfileV1.0，NEQ）
2016-07-11发布
2016-10-01实施
中华人民共和国工业和信息化部发布前
规范性引用文件
3术语、定义和缩略语
3.1术语和定义
3.2缩略语
4用户信息业务概述
资源概述·
资源树信息.
数据类型.
5.3流程图…
6资源定义·
资源：属性名称列表
6.2资源：属性列表·
7错误定义·
7.1服务异常
7.2策略异常
附录A（规范性附录）授权相关：目
附录B（规范性附录）属性名称一一取值对和用户信息名称YD/T3102-2016
YD/T3102-2016
本标准是“基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）”系列标准之一，该系列标准的结构及名称预计如下：一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）短消息和多媒体消息业务：
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）点击拨号业务；一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端状态：一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）终端能力信息业务：
微博业务；
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）搜索业务；一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）地址本：
文件传输业务：
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）定位业务：
状态呈现业务；
一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）1聊天业务；
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）用户信息业务：
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）支付业务；一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）视频共享：
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）图片共享：一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（APID）文感知业务：
移动互联网用户上下
一一基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）非结构化补充数据业务。
随着技术和市场的发展，还将根据情况制定后续相关标准。本标准按照GB/T1.1-2009给出的规则起草。本标准使用重新起草法参考OMA-TS-REST_NetAPI_CustomerProfile-V1_0《基于表述性状态转移（REST）技术的用户信息网络应用程序接口（API）》编制，与OMA-TS-REST_NetAPI_CustomerProfile-V10一致性程度为非等效。本标准与OMA-TS-RESTNetAPICustomerProfile-V1O的主要技术差异如下：
一一修改用户属性名称-取值对和用户信息名称：一一对应用户属性名称-取值对和用户信息名称的修改，修改相关示例：一删除附录A-附录F。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。本标准由中国通信标准化协会提出并归口。I
iiiKAoNiKAca
YD/T3102-2016
本标准起草单位：中国联合网络通信集团有限公司、中国电信集团有限公司、北京邮电大学、中兴通讯股份有限公司、中国信息通信研究院、华为技术有限公司。本部分主要起草人：杨瑞、王志军、吴琳。m
HiiKAoNiKAca
1范围
基于表述性状态转移（REST）技术的业务能力开放应用程序接口（API）用户信息业务
YD/T3102-2016
本标准规定了基于表述性状态转移（REST）技术的用户信息业务开放应用程序接口（API），包括接口的资源定义、资源操作、数据结构、基本流程和安全要求等。本标准适用于提供用户信息业务能力开放的应用程序接口（API）。2规范性引用文件
下列文件对于本文件的应用是必不可少的。凡事注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。OMA-TS-REST_Common-V1_0-20120724-ARESTful网络API通用定义（CommondefinitionsforRESTfulNetworkAPIs)
OMA-SUP-XSD_rest_netapi_customerprofile-V1_0-20130305-C用户信息RESTful网络APIXML结构（(XMLschemafortheRESTfulNetworkAPIforCustomerProfile）OMA-ER-Autho4API-V1_0-20131120-C网络API授权架构（AuthorizationFrameworkforNetworkAPIs）
W3CXMLSchemal可扩展标识语言架构第1部分：结构（第二版）（XMLSchemaPart1：StructuresSecond Edition)
W3CXMLSchema2可扩展标识语言架构第2部分：数据类型（第二版）（XMLSchemaPart2：DatatypesSecondEdition)
3术语、定义和缩略语
3.1术语和定义
下列术语和定义适用于本文件。3.1.1
表述性状态转移RepresentationalStateTransfer一种针对网络应用的设计和开发方式，指的是一组架构约束条件和原则，可以降低开发的复杂性，提高系统的可伸缩性。
3.2缩略语
下列缩略语适用于本文件。
Application Programming InterfaceHyperText Transfer Protocol
Identifier
Representational StateTransfer应用程序编程接口
超文本传送协议
标识符
表述性状态转移
HiiKAoNiKAca
YD/T3102-2016
UniformResourceIdentifier
Uniform Resource Locator
AnonymousCustomerReference
eXtensible Markup Language
XMLSchema Definition
4用户信息业务概述
统一资源标识符
统一资源定位符
匿名用户参考
可扩展标记语言
XML架构定义
用户信息业务是指在保障用户隐私安全的前提下，应用获取用户在服务提供商记录的各种信息，包括身份信息、地址信息、工作信息、教育信息、账户信息等，以便为用户提供更优质、更便利的服务。5资源概述
5.1资源树信息
本节简要概括了REST风格的用户信息API中使用的资源。\apiVersion\URL变量需要用\v1\的值来表明本标准对应的API。关于变量语义的说明，见OMA-TS-RESTCommon-V10-20120724-A。图1给出了本标准中定义的资源结构。//(serverRoot)/customerprofile/(apiVersion/(userld)/metadata
TattributeNameList
/attributes
注：资源树中具有HTTP方法的节点以实体箱的形状标注。图1规范中定义的资源结构
表1给出了规范中定义的资源的详细说明、代表的数据类型以及允许的HTTP方法。表1获取用户信息
属性名称列表
属性列表
Base URL: http:// (server
Root:/customerprofile/
(apiVersion)
{userld)/metadata/attribute
NameList
{userld /attributes
数据结构
AttributeNameList
AttributeList
获取属性名称列表
获取属性（支持信
息过滤，以限制属
性数量）
HTTP方法
DELETE
以上资源不允许采用PUT、POST、DELETE方法，返回的HTTP错误码是405，服务器在响应时还应包括“AlloW：GET”字段。
5.2数据类型
5.2.1XML命名空间
iiKAoNiKAca
用户信息数据类型的命名空间：urn:oma:xmlirest:netapi:customerprofile:1YD/T3102-2016
“xsd”命名空间适用于在W3CXMLSchemal、W3CXMLSchema2中定义的XMLSchema数据类型。“common”命名空间适用于在OMA-TS-REST_Common-V1_0-20120724-A中定义的数据类型。本节中数据结构的XMLschema见OMA-SUP-XSD_rest_netapi_customerprofile-V1_0-20130305-C。5.2.2结构
本小节定义了REST化的用户信息API中使用的数据结构。一些结构能够作为所谓的根元素被实例化。本规范定义了一系列属性名称一取值对，见附录B。5.2.3类型：AttributeNameList属性名称列表见表2。
表2AttributeNameList数据结构元素
attributeMetadata
resourceURL
AttributeMetadata
[1..unbounded]
xsd:anyURI
必选/可选
属性元数据（属性名称和对应用户信息）列表。已定义的属性名称、取值及其对应的用户信息，见附录B资源URL
命名为attributeNameList，类型为AttributeNameList的根元素，允许出现在接口的响应消息体中。5.2.4类型：AttributeMetadata属性元数据见表3。
表3AttributeMetadata数据结构元素
attributeName
profileName
xsd:string
xsd:string
必选/可选
属性名称。已定义的属性名称及取值，见附录B用户信息名称，包含对应的属性名称。已定义的属性名称、取值及其对应的用户信息见附录B命名为attributeMetadata，类型为AttributeMetadata的根元素，允许出现在接口的响应消息体中。5.2.5类型：AttributeList
属性列表见表4。
表4AttributeList数据结构
attribute
resourceURL
Attribute[1..unbounded]
xsd:anyURI
必选/可选
包含与用户有关的属性列表。已定义的属性名称及取值见附录B
资源URL
命名为attributeList，类型为AttributeList的根元素，允许出现在接口的响应消息体中。5.2.6类型：Attribute
单个属性见表5。
表5Attribute数据结构
xsd:string
xsd:string
必选/可选
属性名称。已定义的属性名称及取值见附录B属性取值
HiiKAoNiKAca
YD/T3102-2016
5.3流程图
下面的小节描述了典型的场景下的资源、方法和步骤5.3.1获取用户信息元数据
图2展示了获取用户信息元数据（matadata/attributeNameList）的场景。资源地址：
http://(serverRoot)/customerprofile/(apiVersion)/(userld)/metadata/attributeNameList应用程序免费标准下载网bzxz
1.请求获取属性名称列表
响应属性名称列表
服务器
获取属性
名称列表
图2获取用户信息元数据
应用程序使用GET方法，获取被userId标识的用户的信息元数据，并且接收相关信息（即属性名称列表）
5.3.2获取用户信息内容
图3展示了获取用户信息内容（即全部或某个属性）的场景。资源地址：
http://(serverRooty/customerprofile/(apiVersion/(userId)/attributes应用程序
1.请求获取用户信息内容
（多个属性或单个属性）
响应用户信息内容
服务器
获取用户
信息内容
图3获取用户信息内容
应用程序使用GET方法，获取被userld标识的用户的信息内容，并且接收相关信息（即多个属性或单个属性）。
6资源定义
6.1资源：属性名称列表
6.1.1概述
所使用的资源是：
http://(serverRoot)/customerprofile/(apiVersion)/(userld)/metadata/attributeNameList4
HiiKANiKAca
该资源用来获取属性名称列表形式的用户信息元数据。6.1.2请求URL变量
对于所有的HTTP命令，下列请求URL变量是通用的，具体变量名称及说明见表6。表6请求URL变量
serverRoot
apiVersion
userld
YD/T3102-2016
服务器的URL基本构成：hostname+port+basepath。Port和basepath是可选的。例：example.com/exampleAPI
客户端使用的API版本
用户D。例：tel:+19585550100,acr:pseudonym1236.1.3响应代码和错误处理
HTTP响应代码见OMA-TS-RESTCommon-V1_0-20120724-A。异常策略和异常服务的错误代码见第7章。6.1.4GET方法
6.1.4.1描述
该操作用来获取特定用户的已存在的属性名称列表，及关联的用户信息名称（可选）。用户信息涉及用户隐私，为保障用户信息安全，使用本接口需要得到用户授权，且应支持OMA-ER-Autho4API-V10-20131120-C定义的授权框架。授权范围取值见附录A。6.1.4.2例：获取已有属性名称列表6.1.4.2.1 Request
GET/exampleAPI/customerprofile/v1/tel%3A%2B19585550100/metadata/attributeNameListHTTP/1.1Accept: application/xml
Host: example.com
6.1.4.2.2 Response
HTTP/1.1200OK
Date:Thu,24Aug201212:51:59GMTContent-Type: application/xmlContent-Length: nnnn

provinceaddressProfile

cityHiiKAoiKAca
YD/T3102-2016
addressProfile

districtaddressProfile

locationaddressProfile

zipCodeaddressProfile

minAge18verificationProfile

paymentTypeaccountProfile
http://example.com/exampleAP//customerprofile/v1/tel%3A%2B19585550100/metadata/attributeNameList注：本章涉及的示例代码为资料性部分作为参考。6.2
资源：属性列表
6.2.1概述
所使用的资源是：
http:// (serverRoot)/customerprofile/(apiVersion//(userld)/attributes该资源用来获取所有属性或某一个或几个特定属性。请求URL变量
对于所有的HTTP命令，下列请求URL变量是通用的，具体变量名称及说明见表7。6
serverRoot
apiVersion
userld
表7请求URL变量
YD/T3102-2016
服务器的URL基本构成：hostname+port+basepath.Port和basepath是可选的。
example.com/exampleAPI
客户端使用的API版本
用户ID。例：tel:+19585550100,acr:pseudonym1236.2.3响应代码和错误处理
HTTP响应代码见OMA-TS-RESTCommon-V10-20120724-A。异常策略和异常服务的错误代码见第7章。6.2.4GET
该操作用来获取指定用户信息的属性。例：
用户信息涉及用户隐私，为保障用户信息安全，使用本接口需要得到用户授权，且应支持OMA-ER-Auth04API-V10-20131120-C定义的授权框架。授权范围取值见附录A。属性名称-取值对的选择需使用查询参数“attrFilter\和/或“profFilter\。使用“attrFilter\，返回某个属性名称-取值对，使用“profFilter\，返回指定用户信息中的一系列属性名称一取值对。请求URL中支持的查询参数见表8。表8请求URL变量
attrFilter
profFilter
xsd:string
xsd:string
必选/可选
6.2.4.1例1：获取所有已存在属性6.2.4.1.1 Request
指定属性
1.此查询参数的语法为：
attrFilter=attrFilterValue，attrFilterValue是属性名称列表中的某个属性名称，多个属性名称之间使用&分隔。
2.如果attrFilterValue=attributename（如“givenName\），响应报文主体中仅包含选定的属性，即“givenName\。3.如果attrFilter和profFilter两个参数均不使用，响应报文中包含所有属性指定用户信息
1.此查询参数的语法为：
profFilter-profFilterValue，profFilterValue是用户信息，多个用户信息之间使用&分隔。
2.如果profFilterValue=profilename（如“addressProfile\），响应报文主体中包含归属于指定用户信息的所有属性（见附录B）3.如果attrFilter和profFilter两个参数均不使用，响应报文中包含所有属性4.如果有多个profFilter参数，响应报文中包含归属于相应用户信息的属性合集。另外，如果同时使用attrFilter，选定的属性应在上述属性合集内GET/exampleAPI/customerprofile/vl/tel%3A%2B19585550100/attributesHTTP/1.1Accept: application/xml
Host: example.com
YD/T3102-2016
6.2.4.1.2
Response
HTTP/1.1200OK
Date:Thu,24Aug201212:51:59GMTContent-Type: application/xmlContent-Length: nnnn

province
广东


city
深圳


location
龙岗大街


zipCode
98765


minAge18
verifiedTrue


paymentType
prePaid

小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。