LOGO

写bug的代码人的博客

Atom协议官方文档(中文版)

就在我更新网站的时候,突发奇想安弄一个Feed订阅,于是我就开始在网上寻找教程。可是网上的教程都是RSS标准,没有关于Atom标准的。经过半个小时的“探索式冲浪”之后我终于通过 RSS验证[1] 找到了 Syndication | Atom Enabled[2] ,可全是英文的,翻译又过于生硬(谷歌翻译的……emm,不作评价),所以我又重新翻译了一遍。

 

正文开始

什么是Atom

Atom是一种基于XML的网络内容和元数据联合发布格式的名称,也是一种用于发布和编辑属于定期更新的网站的网络资源的应用程序级协议。

所有Atom feeds都必须是格式良好的XML文档,并通过application/atom+xml媒体类型进行标识。

 

关于此文档

此文档的重点是由IETF AtomPub Working Group提供的Atom发布格式(The Atom Syndication Format)。

如果本文件与互联网草案不同,则以互联网草案为准。

 一般注意事项:

本文档中描述的所有元素都必须位于http://www.w3.org/2005/Atom命名空间中。

Atom 中的所有时间标识都必须符合RFC 3339

除非另有说明,所有值都必须是纯文本(即没有实体编码的 html)。

xml:lang可用于识别任何人类可读文本的语言。

xml:base可用于控制解析相对URI的方式

 

Feed示例

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

  <title>Example Feed</title>
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

 

<feed> 的元素

Feed 由一些元数据组成,它后面可以跟任意数量的条目。

feed必需的元素

以下是feed中必需的元素的列表,每个元素都有简要描述和示例。

id    使用通用的,唯一且永久的URI来标记Feed。如果您的域名有长期、可续订的租约,那么您可以随意使用您的域名。

<id>http://example.com/</id>

title    包含Feed的可读标题。通常与关联网站的标题相同。该值不应为空。

<title>Example, Inc.</title>

updated      表示上次对 Feed 进行重大修改的时间。

<updated>2003-12-13T18:30:02Z</updated>

 

推荐的Feed元素

如下, Atom 对 Feed 元素提出了许多您应该注意的其他要求和建议。

author  指出提要的一位作者的姓名。一个提要可以有多个author元素。(除非所有元素都至少包含一个author元素,否则Feed 必须包含至少一个元素)。点击此处获取更多信息

<author>
  <name>John Doe</name>
  <email>JohnDoe@example.com</email>
  <uri>http://example.com/~johndoe</uri>
</author>

link  用于标识相关的网页。关系的类型由rel属性定义。在每个hreflang和type下,一个Feed只能有一个alternate值(原文:A feed is limited to one alternate per type and hreflang.)。Feed应包含返回Feed本身的链接。点击此处获取更多信息

<link rel="self" href="/feed" />

 

可选的Feed元素

以下是可选的Feed元素的列表

category   指定提要所属的类别。一个Feed可以有多个category元素。点击此处获取更多信息

<category term="sports"/>

contributor  指定Feed的一位贡献者。一个Feed可以有多个contributor 元素。点击此处获取更多信息

<contributor>
  <name>Jane Doe</name>
</contributor>

generator   用标识用于生成Feed、调试和其他目的的软件。uri和version属性都是可选的。

<generator uri="/myblog.php" version="1.0">
  Example Toolkit
</generator>

icon   标识较小的图像,为Feed提供标志性的视觉识别。图标应该是方形的。

<icon>/icon.jpg</icon>

logo   标识较大的图像,为Feed提供标志性的视觉识别。图像的宽度应是高度的两倍。

<logo>/logo.jpg</logo>

rights   传达有关entry中所拥有的权利(例如版权)的信息。点击此处获取更多信息

<rights> © 2005 John Doe </rights>

subtitle   包括可读的描述或副标题。

<subtitle>all your examples are belong to us</subtitle>

 

<entry> 的元素

entry的一个示例是博客上的单个帖子。

<entry> 必需的元素

以下是所需的Feed元素的列表,每个元素都有简要说明和示例。

id   使用通用的,唯一且永久的URI来标识条目。如果 Feed 中的两个entry在不同时间点表示相同的entry,则它们可以具有相同的 id 值。

<id>http://example.com/blog/1234</id>

title   包含该entry的可读标题。该值不应为空。

<title>Atom-Powered Robots Run Amok</title>

updated   表示上次对entry进行重大修改的时间。该值在修复拼写错误后无需更改,只需进行实质性修改即可。通常情况下,Feed中的不同entry将具有不同的更新时间。

<updated>2003-12-13T18:30:02-05:00</updated>

 

<entry>的推荐元素

Atom 对您应该注意的entry元素提出了许多附加要求和建议。它们如下:

author   指出该entry的一位作者。一个条目可能有多个作者。一个entry必须至少包含一个author元素,除非封闭feed元素中存在author元素,或者封闭的source元素中存在author元素。点击此处获取更多信息

<author>
  <name>John Doe</name>
</author>

content   包含或链接到entry的完整内容。如果没有alternate链接则必须被提供,如果没有summary则应该被提供。点击此处获取更多信息

<content>complete story here</content>

link   标识相关网页。关系的类型由rel属性定义。在每个hreflang和type下,一个entry只能有一个alternate。若没有content元素,则必须包含alternate链接。点击此处获取更多信息

<link rel="alternate" href="/blog/1234"/>

summary   传达entry的简短概括、总结或摘录。如果没有为entry提供内容,或者该内容不是内联的(即包含 src 属性),或者内容是用 base64 编码的,则应提供摘要。点击此处获取更多信息

<summary>Sometext.</summary>

 

<entry> 可选的元素

以下是可选元素的列表。

category   指定entry所属的类别。一个entry可以有多个category元素。点击此处获取更多信息

<category term="technology"/>

contributor   列出该entry的一位贡献者。一个条目可以有多个contributor元素。点击此处获取更多信息

<contributor>
  <name>Jane Doe</name>
</contributor>

published   包含entry的初始创建或首次可访问的时间。

<published>2003-12-13T09:17:51-08:00</published>

source   当entry从一个Feed复制到另一个Feed 中的,并且源feed包含任何一个子元素author、contributor、rights或category,且这些子元素不存在源entry中,则应保留源feed的元数据(除entry元素之外的所有的feed子元素)。

<source>
  <id>http://example.org/</id>
  <title>Fourty-Two</title>
  <updated>2003-12-13T18:30:02Z</updated>
  <rights>© 2005 Example, Inc.</rights>
</source>

rights   传达有关entry中所拥有的权利(例如版权)的信息。点击此处获取更多信息

<rights type="html">
  &amp;copy; 2005 John Doe
</rights>

 

常见结构

Category

<category>具有一个必需属性term,以及两个可选属性scheme和label。

term用于标识类别

scheme通过URI标识分类体系。

label提供人类可读的显示标签

 

Content

<content>包含或链接到entry的完整内容。

在最常见的情况下,type属性是text、html、xhtml,在这种情况下,内容元素的定义与其他文本构造相同,如这里所述。

此外,如果该src属性存在,则表示可以找到内容的URI 。该type属性(如果存在)是内容的媒体类型。

      如果属性以或type结尾,则内联包含此类型的 xml 文档。+xml/xml

      如果type属性以 开头text,则内联包含此类型的转义文档。

      将内嵌包含指定媒体类型的Base64编码文档。

 

Link

<link>是按照 html 的 link 元素设计的。它有一个必需属性href和五个可选属性:rel、type、hreflang、title和length。

href是引用资源的URI(通常是网页)

rel包含单个链接关系类型。它可以是完整的URI(参考可扩展性),或以下预定义值之一(默认值为alternate):

alternate:条目或提要的替代表示形式,例如条目的 html 版本或博客首页的永久链接。

enclosure:相关资源的大小可能很大,可能需要特殊处理,例如音频或视频录制。

related:与条目或提要相关的文档。

self: 饲料本身。

via:条目中提供的信息来源。

type指示资源的媒体类型。

hreflang指示引用资源的语言。

title有关链接的人类可读信息,通常用于显示目的。

length资源的长度,以字节为单位。

 

Person

<author>和<contributor>描述个人、公司或类似的实体。它具有一个必需的元素name和两个可选的元素:uri、email。

<name>传达此人的名称。

<uri>包含此人的网站主页。

<email>包含此人的电子邮件地址。

 

Text

<title>、<summary>、<content>、 和<rights>包含人类可读的文本,通常数量很少。该type属性决定了该信息的编码方式(默认为“text”)

如果type="text",则此元素包含纯文本,没有实体转义的 html。

<title type="text">AT&amp;T bought by SBC!</title>

如果type="html",则该元素包含实体转义的 html。

<title type="html">
  AT&amp;amp;T bought &lt;b&gt;by SBC&lt;/b&gt;!
</title>

如果type="xhtml",则此元素包含内联 xhtml,包装在 div 元素中。

<title type="xhtml">
  <div xmlns="http://www.w3.org/1999/xhtml">
    AT&amp;T bought <b>by SBC</b>!
  </div>
</title>

 

Atom扩展

Atom 的content元素旨在支持直接包含其他 XML 词汇表。

任何完全限定的URI都可以用作link元素的 rel 属性的值。

来自其他名称空间的元素几乎可以包含在任何地方。这意味着大多数 RSS 1.0 和 RSS 2.0 模块都可以在 Atom 中使用。

 

参考资料

   [1] FEED Validator. FEED Validator  [引用日期 2023年8月8日]

   [2] Atom Enabled. Syndication|Atom Enabled  [引用日期 2023年8月8日]

 

Posted 2023-08-08 08:04 写bug的代码人

本文标签:

本文总阅读量?

翻译者   写bug的代码人

文章链接   https://bugcoder.asia/article/018.html

声明   本博客中的所有文章均使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权,转载需注明来源

特殊声明  该文章由 写bug的代码人 翻译,翻译内容仅供参考,本文中所有内容以及代码的解释权归Atom Enabled所有