1、 ETSI TS 118 109 V1.1.0 (2016-03) oneM2M; HTTP Protocol Binding (oneM2M TS-0009 version 1.5.1 Release 1) TECHNICAL SPECIFICATION oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)2Reference RTS/oneM2M-000009v110 Keywords IoT,M2M,PROTOCOL ETSI 650 Route des Lucioles F-06921
2、Sophia Antipolis Cedex - FRANCE Tel.: +33 4 92 94 42 00 Fax: +33 4 93 65 47 16 Siret N 348 623 562 00017 - NAF 742 C Association but non lucratif enregistre la Sous-Prfecture de Grasse (06) N 7803/88 Important notice The present document can be downloaded from: http:/www.etsi.org/standards-search Th
3、e present document may be made available in electronic versions and/or in print. The content of any electronic and/or print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any existing or perceived difference in contents between such
4、 versions and/or in print, the only prevailing document is the print of the Portable Document Format (PDF) version kept on a specific network drive within ETSI Secretariat. Users of the present document should be aware that the document may be subject to revision or change of status. Information on
5、the current status of this and other ETSI documents is available at https:/portal.etsi.org/TB/ETSIDeliverableStatus.aspx If you find errors in the present document, please send your comment to one of the following services: https:/portal.etsi.org/People/CommiteeSupportStaff.aspx Copyright Notificati
6、on No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm except as authorized by written permission of ETSI. The content of the PDF version shall not be modified without the written authorization of ETSI. The copyright and t
7、he foregoing restriction extend to reproduction in all media. European Telecommunications Standards Institute 2016. All rights reserved. DECTTM, PLUGTESTSTM, UMTSTMand the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members. 3GPPTM and LTE are Trade Marks of ETSI registered f
8、or the benefit of its Members and of the 3GPP Organizational Partners. GSM and the GSM logo are Trade Marks registered and owned by the GSM Association. oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)3Contents Intellectual Property Rights 5g3Foreword . 5g31 Scope 6g32 Re
9、ferences 6g32.1 Normative references . 6g32.2 Informative references 6g33 Abbreviations . 7g34 Conventions 7g35 Overview on HTTP Binding 7g35.1 Introduction 7g35.2 Request-Line 8g35.3 Status-Line . 8g36 HTTP Message Mapping 8g36.1 Introduction 8g36.2 Parameter Mappings on Request-Line . 9g36.2.1 Met
10、hod 9g36.2.2 Request-Target 9g36.2.2.1 Path component 9g36.2.2.2 Query component . 10g36.2.3 HTTP-Version 12g36.3 Status-Line . 12g36.3.1 HTTP-Version 12g36.3.2 Status-Code . 12g36.3.3 Reason-Phrase . 13g36.4 Header Fields 13g36.4.0 Introduction. 13g36.4.1 Host . 13g36.4.2 Accept. 14g36.4.3 Content-
11、Type 14g36.4.4 Content-Location 14g36.4.5 Content-Length . 14g36.4.6 Etag . 14g36.4.7 X-M2M-Origin . 14g36.4.8 X-M2M-RI 14g36.4.9 Void 14g36.4.10 X-M2M-GID. 14g36.4.11 X-M2M-RTU 15g36.4.12 X-M2M-OT 15g36.4.13 X-M2M-RST 15g36.4.14 X-M2M-RET 15g36.4.15 X-M2M-OET 15g36.4.16 X-M2M-EC. 15g36.4.17 X-M2M-R
12、SC 15g36.5 Message-body . 15g36.6 Message Routing 15g37 Security Consideration . 15g37.1 Authentication on HTTP Request Message 15g37.2 Transport Layer Security 16g3Annex A (informative): Example Procedures 17g3A.1 resource creation 17g3Annex B (informative): WebSocket 18g3oneM2M TS-0009 version 1.5
13、.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)4B.1 Notification using WebSocket 18g3History 19g3oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)5Intellectual Property Rights IPRs essential or potentially essential to the present document may have been declared to ETSI
14、. The information pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: “Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards“, which is availabl
15、e from the ETSI Secretariat. Latest updates are available on the ETSI Web server (https:/ipr.etsi.org/). Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000
16、314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document. Foreword This Technical Specification (TS) has been produced by ETSI Partnership Project oneM2M (oneM2M). oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)61
17、 Scope The present document will cover the protocol specific part of communication protocol used by oneM2M compliant systems as RESTful HTTP binding. The scope of the present document is (not limited to as shown below): Binding oneM2M Protocol primitive types to HTTP method. Binding oneM2M response
18、status codes (successful/unsuccessful) to HTTP response codes. Binding oneM2M RESTful resources to HTTP resources. The present document is depending on Core Protocol specification (ETSI TS 118 104) for data types. 2 References 2.1 Normative references References are either specific (identified by da
19、te of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies. The following referenced documents are necessary for the
20、 application of the present document. 1 IETF RFC 7230 (June 2014): “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing”. 2 ETSI TS 118 103: “oneM2M; Security Solutions (oneM2M TS-0003)“. 3 ETSI TS 118 104: “oneM2M; Service Layer Core Protocol Specification (oneM2M TS-0004)”. 4 RFC723
21、5: “Hypertext Transfer Protocol (HTTP/1.1): Authentication”, IETF, June 2014. 5 RFC6750: “The Oauth 2.0 Authorization Framework: Bearer Token Usage”, October 2012. 6 ETSI TS 118 111: “oneM2M; Common Terminology (oneM2M TS-0011)“. 7 ETSI TS 118 101: “oneM2M; Functional Architecture (oneM2M TS-0001)“.
22、 8 IETF RFC 7232 (June 2014): “Hypertext Transfer Protocol (HTTP/1.1): “Conditional Requests”. 2.2 Informative references References are either specific (identified by date of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applie
23、s. For non-specific references, the latest version of the referenced document (including any amendments) applies. The following referenced documents are not necessary for the application of the present document but they assist the user with regard to a particular subject area. i.1 oneM2M Drafting Ru
24、les. NOTE: Available at http:/www.onem2m.org/images/files/oneM2M-Drafting-Rules.pdf. i.2 IETF RFC 6455 (December 2011):”The WebSocket Protocol”. oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)73 Abbreviations For the purposes of the present document, the following abbrev
25、iations and those given in ETSI TS 118 111-Common Terminology 6 apply: AE Application Entity CSE Common Services Entity CSE-ID Common Service Entity Identifier HTTP Hyper Text Transfer Protocol IN-CSE Infrastructure Node Common Services Entity TLS Transport Layer Security MN-CSE Middle Node Common S
26、ervices Entity URI Uniform Resource IdentifierXML eXtensible Markup Language 4 Conventions The keywords “Shall”, “Shall not”, “May”, “Need not”, “Should”, “Should not” in this document are to be interpreted as described in the oneM2M Drafting Rules i.1. 5 Overview on HTTP Binding 5.1 Introduction HT
27、TP binding specifies the equivalence between oneM2M request and response primitives and HTTP request and response messages, respectively. This clause provides a brief overview on the mapping relationship between oneM2M and HTTP message parameters. This clause describes how oneM2M request/response pr
28、imitives can be mapped to HTTP request/response messages and vice versa. Figure 5.1-1 illustrates an example oneM2M system configuration and its correspondence to an HTTP-based information system if HTTP binding as defined in the present document is applied. The upper diagram in Figure 5.1-1 shows w
29、ith solid line arrows the flow of a request primitive originating from an AE which is registered to an MN-CSE (Registrar of AE). The request primitive is assumed to address a resource which is hosted by another MN-CSE (Host of Resource). Both MN-CSEs are registered to the same IN-CSE. When applying
30、HTTP binding, the oneM2M entities of the upper diagram take the roles outlined in the lower diagram of a corresponding HTTP information system as defined in 1. The AE takes the role of an HTTP client, the MN-CSE (Registrar of AE) takes the role of a HTTP Proxy Server, and both the IN-CSE and MN-CSE
31、(Host of Resource) take the role of a HTTP server for this particular request message. CSEs may also issue unsolicited request messages, shown with dashed line arrows in Figure 5.1-1, and receive associated response messages. Therefore, for HTTP protocol binding, CSEs generally provides capability o
32、f both HTTP Server and HTTP Client. Aes may provide HTTP Server capability optionally in order to be able to serve Notification request messages (see ETSI TS 118 104 3 and ETSI TS 118 101 7). oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)8Figure 5.1-1 : Correspondence b
33、etween oneM2M entities and HTTP Client and Server Each individual request primitive will be mapped to single HTTP request message, and each individual response primitive will be mapped to a single HTTP response message, and vice-versa. An HTTP request message consists of Request-Line, headers and me
34、ssage-body. An HTTP response message consists of Status-Line, headers and message-body 1. HTTP header names are case-insensitive and a Receiver shall accept headers that are either lower or upper or any mixture thereof. This clause describes how oneM2M request/response primitives are mapped to HTTP
35、messages at a high level. Corresponding details are specified in clause 6. 5.2 Request-Line The HTTP method of a request message is mapped to the Operation parameter, and vice-versa. At the message originator side the HTTP Request-Target is derived from the To parameter of the request primitive, inc
36、luding a query string which carries other specific primitive parameters. HTTP-Version is specified in clause 6. 5.3 Status-Line HTTP Version is specified in clause 6. The Status-Code of HTTP response messages is derived from the Response Status Code parameter of the response primitive. The Reason-Ph
37、rase is not applicable to oneM2M systems and is omitted. 6 HTTP Message Mapping 6.1 Introduction Mapping between oneM2M primitives and HTTP messages shall be applied in the following four use cases: 1. Mapping of request primitive to HTTP request message at the request originator (HTTP client) 2. Ma
38、pping of HTTP request message to request primitive at the request receiver (HTTP server) 3. Mapping of response primitive to HTTP response message at the request receiver (HTTP server) oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)94. Mapping of HTTP response message to
39、 response primitive at the request originator (HTTP client) All four use cases also appear at transit CSEs. The following clauses specify the mapping between each oneM2M primitive parameter and a corresponding HTTP message field to compose a HTTP request/response message. 6.2 Parameter Mappings on R
40、equest-Line 6.2.1 Method The HTTP Method shall be derived from the Operation request primitive parameter of the request primitive. Table 6.2.1-1: HTTP Method Mapping oneM2M Operation HTTP Method Create POST Retrieve GET Update PUT Delete DELETE Notify POST At the Receiver, an HTTP request message wi
41、th POST method shall be mapped either to a Create or Notify Operation parameter. Discrimination between Create and Notify operations can be accomplished by inspection of the content-type header. The Resource Type parameter is present in the content-type header only when the HTTP POST request represe
42、nts a Create request (see clause 6.4.3). The Resource Type parameter is not present in the content-type header when the HTTP POST request represents a Notify request. 6.2.2 Request-Target 6.2.2.1 Path component The path component of the origin-form HTTP Request-Target shall be interpreted as the map
43、ping of the resource identifier part of the To request primitive parameter. If the HTTP message is sent directly to the next hop CSE, the origin-form of Request-Target shall be employed (see clause 5.3.1 of 1). The resource identifier part of the To parameter can be represented in three different fo
44、rms (see clause 6.2.3 3 and clause 7.2 7): CSE-Relative-Resource-ID, SP-Relative-Resource-ID, Absolute-Resource-ID. Each of the above three formats may include either a structured Resource ID (used for hierarchical addressing) or an unstructured Resource ID (used for non-hierarchical addressing) as
45、defined in clause 7.2 7. For CSE-relative Resource ID representation, the path component of the HTTP request message shall be constructed as the concatenation of the literal “/” and the To request primitive parameter. For SP-relative Resource ID representation, the path component of the HTTP request
46、 message shall be constructed as the concatenation of the literal “/” and the To request primitive parameter. For Absolute Resource ID representation, the path component of the HTTP request message shall be constructed by replacing the first “/” character of the To request primitive parameter with “
47、/_”. The Table below shows valid mappings between the To request primitive parameter and the path component of the origin-form HTTP request target. In the shown examples, /myCSEID and /CSE178 represent applicable CSI-IDs, CSEBase represents the resource name of a resource, CSEBase/ae12/cont27/contIn
48、st696 represents a structured CSE-relative resource ID, and cin00856 an unstructured CSE-relative resource ID. oneM2M TS-0009 version 1.5.1 Release 1 ETSI ETSI TS 118 109 V1.1.0 (2016-03)10Table 6.2.2.1-1: Mapping examples between To parameter and path component of request-line Resource-ID Type To p
49、arameter value path component (origin-form) structured CSE-Relative CSEBase/ae12/cont27/contInst696 /CSEBase/ae12/cont27/contInst696/ unstructured CSE-Relative cin00856 /cin00856 structured SP-Relative /CSE178/CSEBase/ae12/cont27/contInst696 /CSE178/CSEBase/ae12/cont27/contInst696 unstructured SP-Relative /CSE178/cin00856 /CSE178/cin00856 structured Absolute /mym2msp.org/CSE178/CSEBase/ ae12/cont27/contInst696 /_/mym2msp.org/CSE178/CSEBase/ ae12/cont27/contInst696 unstructured Absolute /mym2msp.org/CSE178/cin008
