RFC6690-受限RESTful环境(CoRE)链接格式 翻译

最近在学习CoAP协议，网上相关资料很少，于是自己各种翻RFC文档。看这篇比较短，干脆直接几乎整篇翻译下来给大家参考。后面再出个CoAP学习的笔记。

Last updated 2015-10-14

RFC文档网上都是公开的，应该没有版权问题，如有请联系我删除。仅供学习交流使用，请勿用于商业用途。

文章目录

• • 受限RESTful环境(CoRE)链接格式
• 1 介绍
• • 1.1 CoRE中的Web Linking
  • 1.2 用例
  • • 1.2.1 发现
    • 1.2.2 资源集合
    • 1.2.3 资源目录
  • 1.3 术语
• 2 链接格式
• • 2.1 目标和上下文URI
  • 2.2 链接关系
  • 2.3 使用锚
• 3 CoRE链接属性
• • 3.1 资源类型属性 — ‘rt’
  • 3.2 接口描述属性 — ‘if’
  • 3.3 最大尺寸估计属性 — ‘sz’
• 4 众知接口
• • 4.1 查询过滤
• 5 示例
• 6 安全考虑
• 7 IANA考虑
• • 7.1 众知 ‘core’ URI
  • 7.2 新关系类型 ‘hosts’
  • 7.3 新因特网媒体类型 ‘link-format’
  • 7.4 受限RESTful环境(CoRE)参数注册
• 8 鸣谢
• 9 参考文献

受限RESTful环境(CoRE)链接格式

摘要

这篇规范使用一个链接(link)格式定义了Web Linking，给条件受限的Web服务器用于描述拥有的资源、它们的属性以及链接间的其他关系。基于RFC5988中定义的HTTP Link头部字段，受限RESTful环境(CoRE)链接格式被携带在payload中，并被赋值了一个因特网媒体类型。“RESTful”指的是表征状态转移(REST)架构。一个知名URI被定义为默认入口点，用于请求服务器拥有的链接。

1 介绍

受限RESTful环境(CoRE)以适合于最受限节点(例如带有有限内存的8位微控制器)和网络(例如6LoWPANs)的格式，实现了表征状态转移架构[REST]。CoRE致力于 Machine-to-Machine(M2M) 应用，例如智能能源和楼宇自动化。

在没有人工协助并且静态接口很不好用的M2M应用中，能发现受限服务器拥有的资源是十分重要的。我们把HTTP web服务器所提供资源的发现[RFC2616]称作“Web发现(discovery)”，把资源间关系的描述[RFC5988]称作“Web Linking”。在当前的规范中，我们把发现 受限web服务器拥有的资源、它们的属性以及其他资源关系 称为CoRE资源发现(CoRE Resource Discovery)。

这样一个发现机制的主要功能是为服务器拥有的资源提供通用资源标识符(URI，也称为链接)，加上相关的属性以及可能有的进一步链接关系。在CoRE中，这个链接集合自身就是一个资源(不同于HTTP头部中携带特定资源的那种方式)。这篇文档指定了用于CoRE资源发现的链接格式，通过扩展HTTP Link头部格式[RFC5988]来阐述这些链接描述。CoRE链接格式被携带在payload中，并被赋值了一个因特网媒体类型。众知相对URI“/.well-known/core”被定义为CoRE资源发现的默认入口点，用于请求服务器拥有的资源的链接列表。这篇规范可用于受限应用协议(CoAP)、HTTP或任何其他合适的web传输协议。这链接格式也可以被存储为文件格式。

1.1 CoRE中的Web Linking

技术上，CoRE链接格式是[RFC5988]中指定的typed link的一个序列化，其用于描述资源间的关系，所以被叫做“Web Linking”。在这篇规范中，用特定的受限M2M属性对Web Linking进行了扩展；链接不是放在HTTP Link头部字段中，而是被作为消息payload携带，还定义了一个默认接口来发现服务器拥有的资源。这篇规范还定义了一个新的关系类型“hosts”(来自动词“to host”)，它指明资源为哪个服务器拥有，链接文档就是从哪个服务器上请求来的。

在HTTP中，Link头部可以用于与一个HTTP答复一同携带资源的链接信息。这个方式在web服务器和浏览器下工作的很好，这个用例中，在获取一个特定资源后，它的进一步信息十分有用。在CoRE中，Web链接的主要用法是在最开始的地方发现一个主机拥有的资源。尽管一些资源可能有进一步关联的链接，那应该只是个例外。因此，CoRE链接格式序列化被作为一个众知URI的资源陈述(representation)。CoRE链接格式重用了定义在[RFC5988]中的HTTP Link头部序列化格式。

1.2 用例

在当今web世界中，Web Linking的典型用法包括：描述一个网页的作者或者描述网页间的关系(如下一章、前一章)。Web Linking也可以用于M2M应用，在M2M应用中，typed links被用来协助一个机器客户端去找到和理解怎么使用一个服务器上的资源。在这个章节中，我们提供了一些用例来描述CoRE链接格式可以怎么用于M2M应用。想要更多技术示例的话，见第5章。有大量的M2M应用，我们特意选了些常见的。这篇规范假设不同的部署和应用领域会以合适的资源类型来定义合适的REST接口描述，这样资源发现才有意义。

1.2.1 发现

在M2M应用中，例如家居或楼宇自动化，需要本地客户端和服务器在没有人工干涉的情况下相互发现和交互。在这种环境下，CoRE链接格式可以被服务器用于支持发现服务器上的资源。

资源发现可以用单播或多播来完成。当服务器的IP地址已知，不管是预知的还是通过DNS[RFC1034]解析出来的，我们会使用单播发现以定位入口点为想要的资源。在这篇规范中，这是通过GET服务器上的“/.well-known/core”来实现的，这会返回一个CoRE链接格式的payload。客户端随后会匹配自己应用需要的资源类型、接口描述和可能的媒体类型[RFC2045]。可能还会再请求字符串中包含一些属性以过滤答复中返回的链接的数量。

当一个客户端需要在有限的范围中定位资源，且这域支持IP多播时，多播资源发现十分有用。一个GET请求会在合适的多播地址上请求“/.well-known/core”。为了限制答复的数量和大小，推荐使用带有已知属性的请求字符串。典型地，会基于资源类型 和/或 接口描述 以及 可能的应用特定属性来发现资源。

1.2.2 资源集合

M2M接口的RESTful设计经常会使用资源集合(collections)。比如，数据汇聚节点中温度传感器索引或者家庭安全控制器的警报器列表。CoRE链接格式可以用来发现集合的入口点并访问到它的成员。集合的入口点总是包含在“/.well-known/core”中以使它能被发现。集合的成员可以通过带有集合大小参数的资源接口描述或者通过使用链接格式描述集合中的每个资源来定义。这些链接可以位于“/.well-known/core”，或者放在集合的根资源下。

1.2.3 资源目录

在许多部署常见下，比如受限网络下的休眠服务器或者带宽受限网络下大型M2M部署，部署资源目录实体是有意义的，资源目录上存储着存于其他服务器上的资源的链接。可以把它想象成一个用于受限M2M资源的受限搜索引擎。

CoRE链接格式可被服务器用于注册资源到一个资源目录上，或者用于使资源目录能轮询资源。资源注册可以通过让每个服务器POST它们的资源到资源目录的“/.well-known/core”上来实现。这会添加链接到资源目录合适的资源下。然后这些链接可以被任何客户端发现，客户端会发送请求到资源目录的查询接口。

1.3 术语

这篇规范中的关键词"MUST(必须)", “MUST NOT(绝不能)”, “REQUIRED(要求)”, “SHALL(应当)”, “SHALL NOT(不应当)”, “SHOULD(应该)”, “SHOULD NOT(不应该)”, “RECOMMENDED(推荐)”, “MAY(也许会)”, 和"OPTIONAL(可选)"应该按照[RFC2119]中描述的那样解释。

这篇规范使用了扩展的巴科斯范式(Augmented Backus-Naur Form (ABNF))[RFC5234]表示法，核心规则定义在文档的附件B中。

这篇规范要求读者熟悉[RFC5988]和[RFC6454]中所谈论的所有术语和概念，这篇规范使用以下术语：

Web Linking

  一个框架，用于指明web资源间的关系。

链接(Link)

  在[RFC5988]中也被叫做“typed links”。一个链接就是两个由URI标识的资源间的一个有类型的连接，包含一个context URI、一个链接关系类型、一个目标URI和可选的目标属性。

链接格式(Link Format)

  typed links的一个特别的序列化。

CoRE链接格式

  typed links的一个特别的序列化，其基于定义在[RFC5988]第五章中的HTTP Link头部字段序列化，但被携带为有媒体类型的一个资源陈述。

属性(Attribute)

  更准确的说应该是[RFC5988]中的“目标属性”。一个描述链接或者它的目标的键值对。

CoRE资源发现

  就是当一个客户端通过访问"/.well-known/core"来发现服务器拥有的资源列表，它们的属性以及其他链接关系。

2 链接格式

CoRE链接格式扩展了[RFC5988]中指定的HTTP Link头部字段。它不要求特别的XML或者二进制转换，相当紧凑，并且可扩展 – 这是CoRE的所有重要特性。要注意的是，这个链接格式只是定义在[RFC5988]中的typed links的一个序列化；其他序列化包括HTML links、Atom feed links [RFC4287]、HTTP Link头部字段。我们期望CoRE链接格式中发现的资源也能够以多种格式在更大的因特网上获得。CoRE链接格式仅仅应该用于受限网络和M2M系统。

[RFC5988]的第五章不要求定义的链接格式有一个因特网媒体类型，因为它被定义为携带在HTTP头部中。因此这篇规范将CoRE链接格式(见章节7.3)的因特网媒体类型定义为“application/link-format”。尽管HTTP Link头部字段的编码依赖于[RFC2616]，CoRE链接格式被编码为UTF-8[RFC3629]。CoRE链接格式的解码器并不需要理解UTF-8编码(当然能理解更好)，并且不需要做UTF-8归一化。UTF-8数据可以按位比较，这使得在值中包含UTF-8数据不会导致受限节点增加任何复杂性。

CoRE链接格式等价于[RFC5988]链接格式；然而，当前规范重新给出了ABNF并进行了修改以兼容[RFC5234]并包含了新的链接参数。这篇规范中保留了链接参数“href”用作过滤请求参数(见4.1)，其决不能被定义为链接参数。如[RFC5988]中所述，多个链接参数由逗号分隔。注意，逗号也可以出现在引号包起来的字符串以及URI中，出现在这种地方不会终止一个描述。为了转换HTTP Link头部字段为这个格式，首先，移除“Link:” HTTP头部，移除所有空行，将头部的值转换为UTF-8，然后解码所有的百分号编码。

2.1 目标和上下文URI

每个链接都把一个目标URI表达为一个包含在中括号("<>")中的URI引用。一个链接的上下文URI(在[RFC3986]中也叫作基础URI)由这篇规范中的以下规则定义：

• 当指定anchor参数时，上下文URI就是它。
• 当指定时，是目标URI的源。
• 链接格式资源的基础URI的源。

2.2 链接关系

由于CoRE链接格式中的链接典型地用于描述服务器上拥有的资源，新的关系类型“hosts”是用于缺失关系参数时(见7.2)。“hosts”关系类型(来自动词“to host”)指明目标URI是一个被服务器拥有的资源(即服务器拥有资源)，由上下文URI表明。目标URI必须是这个关系类型的上下文URI的一个相对URI。

为了表达其他关系，链接可以使用任何注册的关系，这通过包含关系参数实现。一个关系的上下文可以使用锚参数定义。用这种方法，就可以表达一个服务器上的资源间或者服务器上资源与外部资源间的关系。

2.3 使用锚

根据[RFC5988]的章节5.2，一个链接描述也许包含一个“anchor”参数，如有，则上下文就是这属性中包含的URI。这用于描述两个资源间的关系。但是实现也可以选择忽视这样的链接。我们并不指望所有的实现都能够从显式的锚链接中提取有用信息。

3 CoRE链接属性

一下CoRE专用的目标属性是定义来补充那些已经定义在[RFC5988]中的。这些属性描述了那些在访问有关系的目标链接时很有用的信息，有些情况下可以使用URI的语义形式。·这样一个URI也许会被解引用(例如，为了获得链接关系的描述)，但是这不是协议的一部分，绝不能在链接评估时自动完成。当比较属性的值的时候，必须作为字符串来比较。

3.1 资源类型属性 — ‘rt’

资源类型属性‘rt’是一个含糊的字符串，用于给一个资源赋值应用专用的语义类型。你可以把它当做一个描述资源的名词。在资源是温度的情景下，它可以是，例如一个应用专用的语义类型如“outdoor-temperature”，或者一个引用本体论中特定概念的URI，如“http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature”。这个温度的值内也许会包含多种资源类型，使用空格分隔，类似于关系属性。资源类型值的注册在章节7.4中定义。

资源类型属性并不是要你给资源赋予一个人类可读的名字。[RFC5988]中定义的“title”属性才是干这个用的。资源类型属性绝不能在一个链接中出现超过一次。

3.2 接口描述属性 — ‘if’

接口描述属性‘if’是一个含糊的字符串，用于提供一个名字或URI以指定一个用于与目标资源交互的专用接口定义。你可以将其视为资源上可用的描述性动词。接口描述属性是要用来描述通用REST接口以与一个资源或资源集合进行交互的。希望接口描述能被不同的资源类型重用。比如，资源类型“outdoor-temperature”、“dew-point”和"rel-humidity"都可以使用接口描述"http://www.example.org/myapp.wadl#sensor"来访问。这个参数的值也许会包含多个接口描述，使用空格分隔，类似于关系属性。资源类型值的注册在章节7.4中定义。

接口描述可以是比如一个web应用描述语言[WADL]的定义，目标资源“http://www.example.org/myapp.wadl#sensor”，一个URN指定资源的接口类型为“urn:myapp:sensor”或者一个应用专用的名字“sensor”。接口描述属性绝不能在一个链接中出现超过一次。

3.3 最大尺寸估计属性 — ‘sz’

最大尺寸估计属性‘sz’标示了当往目标URI上使用GET时返回的资源陈述的最大大小。对于到CoAP资源的链接，这个属性并不期望被用于可以直接舒服地放入单个最大传输单元(MTU)中的小资源，但是应该用于大小大于MTU的资源。最大尺寸估计属性绝不能在一个链接中出现超过一次。

注意，‘sz’属性的值没有定义上限。实现必须准备好接受大的值。一个实现策略是转换任何大于合理大小的值为一个特别的值“Big”，然后在后续处理中就会发现值实在太大了，无法处理。

4 众知接口

CoRE中的资源发现是通过使用一个众知资源URI来实现的，它会返回一个关于服务器拥有的资源和其他链接关系的链接列表。如[RFC5785]中指定的，众知资源有一个以“/.well-known/”开始的路径。这个规范定义了一个用于CoRE资源发现的新众知资源：“/.well-known/core”。

为了资源发现的目的，实现了这篇规范的服务器必须在适当的协议默认端口上支持这个资源。但，这还是取决于包含链接的应用以及它们是怎么组织的。资源“/.well-known/core”是用于返回指向服务器上资源接口入口点的链接的。更复杂的链接组织可以通过包含到服务器上其他地方的CoRE链接格式资源来达成，比如，为了实现索引。当一个链接都没有时，返回一个零长度的payload。这个资源的资源陈述必须是第2章中描述的CoRE链接格式。

CoRE资源发现接口支持以下交互：

• 在默认端口的“/.well-known/core”上执行一个GET，返回CoRE链接格式的可在服务器上访问的链接的集合(如有)。这些链接也许会描述服务器上或者其他服务器上拥有的资源，或者表达其他类型的链接关系，如第二章中描述的。
• 过滤可能会在任何链接格式属性上进行，使用如4.1章中描述的查询字符串。比如，[GET /.well-known/core?rt=temperature-c]将请求资源类型为temperature-c的资源。但是，不要求服务器必须支持过滤。
• 更牛逼的服务器，比如代理，可以实现一个资源目录，通过请求其他端点的资源描述或者允许服务器POST请求到“/.well-known/core”上。但是资源目录功能的细节就不是这篇规范的范畴了，应该要独立规定。

4.1 查询过滤

一个实现了这篇规范的服务器也许会认得资源发现URI的查询部分，将其作为返回的资源的过滤器。路径和查询部分合在一起应该遵从以下4层URI模板[RFC6570]：

/.well-known/core{?search*}

当变量“search”是一个单元素列表，即只有一个键值对时，

• 名字要不就是“href”，定义在这篇规范中的一个 链接-参数 名，要不就是其他 链接-扩展 名，并且
• 值要不就是一个不以“*”(%2A)结尾的完整值的字符串，要不就是一个后面跟着“*”(%2A)的前缀值字符串。

搜索名“href”指向的是一个链接在“<”和“>”间的URI引用。两个值字符串仅在目标属性存在时才匹配。值字符串在进行匹配前会进行百分比编码([RFC3986]的2.1章)；相似的，任何表示为双引号字符串的目标属性都会按照[RFC2616]第2.2章中的定义来解释。完成这些步骤后，如果按位一致的话，一个匹配目标属性的完整值字符串就匹配出来了。匹配目标属性的前缀值字符串则是按位匹配前缀(任何字符串是自身的前缀)。前缀值字符串可以是空的；根据上面的定义，它匹配任何存在的目标属性。要注意的是关系类型目标属性可以包含多个值，在匹配中，每个值都必须当作独立的目标属性。

并不期待每个受限节点都支持过滤。不支持过滤的实现必须简单地忽略查询字符串并为单播请求返回整个资源。

当使用如受限应用协议(CoAP)这样支持多播请求的传输协议时，有些要特别考虑的地方。如果不支持过滤，或者过滤器不匹配，则不应该答复带有查询字符串的多播请求(以免不必要的答复风暴)。除非IP栈接口不能告知使用的是否是多播地址。

以下例子是有效的询问URI的示例：

• ?href=/foo 匹配锚定在/foo的链接值
• ?href=/foo* 匹配锚定在以/foo起始的URI的链接值
• ?foo=bar 匹配目标属性foo的值一字不差的为bar的链接值
• ?foo=bar* 匹配目标属性foo的值以bar起始的链接值，如bar或barley。
• ?foo=* 匹配拥有目标属性foo的链接值

5 示例

后面是一些典型的按这种格式的链接描述。一个陈述中的多个资源描述相互间由逗号分隔。示例中为了可读性还包含了换行。尽管以下示例使用了CoAP答复码，这些示例同样适用于HTTP(对应的答复码会是 200 OK)。

这个示例包含到两个不同传感器的链接，它们共享同个接口描述。要注意的是，这个链接格式的默认关系类型是链接中的“hosts”，它没有rel=target属性。因此，这个示例中的链接告诉我们，/.well-known/core所请求的那个原始的服务器拥有资源/sensors/temp和/sensors/light(分别是一个目标)。

REQ: GET /.well-known/core

RES: 2.05 Content

</sensors/temp>;if=“sensor”,

</sensors/light>;if=“sensor”

不管为了可读性而插入的换行，格式实际上看起来像这样。

</sensors/temp>;if=“sensor”,</sensors/light>;if=“sensor”

这个示例按层次结构排列链接描述，入口点包括指向包含有关传感器的链接的子资源的链接。

REQ: GET /.well-known/core

RES: 2.05 Content

</sensors>;ct=40

REQ: GET /sensors

RES: 2.05 Content

</sensors/temp>;rt=“temperature-c”;if=“sensor”,

</sensors/light>;rt=“light-lux”;if=“sensor”

查询过滤器的示例可能长这个样子：

REQ: GET /.well-known/core?rt=light-lux

RES: 2.05 Content

</sensors/light>;rt=“light-lux”;if=“sensor”

注意，关系类型属性如‘rt’、‘if’和‘rel’可以有多个由空格分隔的值。一个查询过滤器参数可以匹配这些值中的任意一个，如下例：

REQ: GET /.well-known/core?rt=light-lux

RES: 2.05 Content

</sensors/light>;rt=“light-lux core.sen-light”;if=“sensor”

这个示例展示了“anchor”属性的用法，它关联温度 传感器资源到一个外部描述和一个备选URI上。

REQ: GET /.well-known/core

RES: 2.05 Content

</sensors>;ct=40;title=“Sensor Index”,

</sensors/temp>;rt=“temperature-c”;if=“sensor”,

</sensors/light>;rt=“light-lux”;if=“sensor”,

<http://www.example.com/sensors/t123>;anchor="/sensors/temp";rel=“describedby”,

</t>;anchor="/sensors/temp";rel=“alternate”

如果一个客户端想要发现一个特定资源的关系，他可以在anchor参数上进行一个询问。

REQ: GET /.well-known/core?anchor=/sensors/temp

RES: 2.05 Content

<http://www.example.com/sensors/temp123>;anchor="/sensors/temp";rel=“describedby”,

</t>;anchor="/sensors/temp";rel=“alternate”

下例展示了一个大固件资源，带有一个尺寸属性。这个链接的消费者将使用‘sz’属性来确定是否资源陈述过大，以及是否需要进行分块传输。在这个情况下，一个只有64KB闪存的客户端可能只支持16位整型来存储‘sz’属性。因此，应该使用一个特定的flag或值来表示‘Big’(大于64KB)。

REQ: GET /.well-known/core?rt=firmware

RES: 2.05 Content

</firmware/v2.1>;rt=“firmware”;sz=262144

6 安全考虑

这篇规范有如[RFC5988]第七章中描述的安全考虑。“/.well-known/core”资源也许会被保护，比如依据 [COAP] 9.1章，当存储在一个CoAP服务器上时，可以使用数据包传输层加密(DTLS)。

一些服务器也许会为异构的在不同程度上受信的客户端提供资源发现服务。比如，一个轻量的控制系统可能会允许任何客户端读状态变量，但是仅允许特定客户端去写状态(开/关灯)。拥有认证和授权特性的服务器应该支持底层传输协议的认证特性(HTTP或DTLS/TLS)，并支持基于客户端的标识和权限返回不同的链接列表。尽管这样的服务器也许不会给所有请求者返回所有链接，不提供链接不意味着它就会限制对相关资源的访问 — 一个差劲的执行器可能知道或者猜到正确的URI。服务器也可以给出假的可用资源。如果客户端仅能从已知资源获得信息十分重要话，则资源需要被授权。

在CoAP上对众知链接格式资源的多播请求可以用于在受限网络上拒绝服务。一个多播请求应该仅在被充分授权和加密使用时才能接受，比如，使用IPsec或者一个适当的对象加密机制。

CoRE链接格式转换器应该意识到链接描述可能是循环的。即包含指向自己的链接。这些循环的链接可能是直接的，也可能是间接的(即，通过引用的资源)。当转换链接描述和访问循环的链接时应该要小心。

7 IANA考虑

7.1 众知 ‘core’ URI

这个备忘录将‘core’众知URI注册进[RFC5785]中定义的众知URI入口中。

URI后缀：core

变更控制者：IETF

规范文档：RFC 6690

相关的信息：无

7.2 新关系类型 ‘hosts’

这个备忘录注册新Web链接关系类型‘host’，参照[RFC5988]。

关系名：hosts

描述：对于由服务器拥有的一个资源的引用，由链接内容表示。

参考文献：RFC 6690

注意：这个关系是用于CoRE的，在CoRE中，链接是作为"/.well-known/core"资源陈述提取的，其是CoRE链接格式的默认关系类型。

应用数据：无

7.3 新因特网媒体类型 ‘link-format’

这个备忘录为CoRE链接格式注册一个新因特网媒体类型‘application/link-format’。

类型名：application

子类型名：link-format

需求参数：无

可选参数：无

编码考虑：二进制数据(UTF-8)

安全考虑：

请求CoAP众知链接格式资源的多播请求可以在受限网络上用于拒绝服务。只有在请求被使用 如IPsec或合适的对象加密机制 充分授权和加密的情况下，多播请求才会被接收。

CoRE链接格式转换器应该意识到，链接描述可能是循环的，即包含到自己的链接。循环的链接可能是直接的，也可能是间接的(即通过引用的链接资源)。在转换链接描述和访问循环的链接时要十分小心。

互用性考虑：无

发布的规范：RFC 6690

使用这个媒体类型的应用：CoAP服务器和客户端实现来用于资源发现，以及HTTP应用将链接格式作为payload。

额外信息：

幻数：

文件扩展名：*.wlnk

Macintosh文件类型代码：

预期用途：COMMON

使用约束：无

作者：CoRE WG

变更控制者：IETF

7.4 受限RESTful环境(CoRE)参数注册

略

8 鸣谢

略

9 参考文献

略