常见元素:“种类”

警告:本页面介绍的是 Google 的旧版 API,即 Google 数据 API;它仅与 Google 数据 API 目录中列出的许多 API 相关,其中许多 API 已替换为较新的 API。如需了解特定新 API,请参阅新 API 的文档。如需了解如何使用较新的 API 向请求授权,请参阅 Google 帐号身份验证和授权

简介

通常,使用 Google Data API 的服务能够提供有关某一特定项的一致信息集非常有用。

例如,各种 Google 数据 API(简称“GData”)服务可能会为某个人或组织提供联系信息;所有这些服务都使用相同的联系信息元素。

共同描述联系人的元素集合称为“联系人”类型。Contact 种类中的某些元素是普通的 Atom 或 RSS 元素;其他元素由 Google 在名为“Google 数据命名空间”的命名空间中定义。按照惯例,Google 数据命名空间通常在 XML 代码中使用 gd: 别名引用;例如,包含电话号码或传真号码的元素为 <gd:phoneNumber>。Google 数据命名空间的架构网址为 http://schemas.google.com/g/2005。

Google 还定义了其他类型:活动(表示日历事件的标准化元素的集合)和邮件(表示电子邮件、论坛帖子或其他邮件的元素的集合)。

Google 数据命名空间中的某些元素供多种类型使用。例如,<gd:who> 元素会将人(如 <gd:who> 中所述)与包含 <gd:who> 元素的条目相关联。此元素在“事件”种类中用于指定组织者、参加者等。还可在“消息”种类中用于指定发件人和收件人。

当 Google Data API Feed 中的条目使用给定种类时,其中包含一个 <atom:category> 元素,该元素的 scheme 属性设为 "http://schemas.google.com/g/2005#kind",其 term 属性设为架构网址的名称后跟类型的名称。例如,联系人条目包含以下元素:

<atom:category scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/g/2005#contact"/>

这样,客户端便可以快速轻松地确定该条目包含哪类数据,即确定该条目的语义。(如果您愿意,可以使用 RSS,而不是 Atom;如需了解与 Atom 元素对应的 RSS 元素,请参阅协议参考文档。)

本文档将介绍一些常见种类及其包含的元素。

未记录的元素

如果标准元素具有 <atom:entry> 标准含义,则我们不会添加这些元素的相关信息。例如,<atom:id><atom:published><atom:updated> 在出现种类时都会具有标准含义。

我们也不添加在给定上下文中无意义的标准 Atom 元素的信息;例如,<atom:summary> 不用于联系人种类,尽管 <atom:author> 是条目中的必需元素(除非父 Feed 中已指定),但它在联系人种类中不具备实用的含义。

创建种类

您可能很难确切地知道在创建特定类型条目时需要添加哪些信息,尤其是这些类型的某些元素中包含其他类型时。

有一种方法可能会有所帮助,那就是使用我们提供的客户端库,而不是试图手动构建种类。客户端库提供各种用于在给定条目中添加和更改数据的方法;如需了解详情,请参阅客户端库文档。

可扩展性

本文档中的信息并未涵盖种类的所有可能属性和属性值。服务可能会扩展种类,因此特定服务可能会使用未包含在本文档中的属性和值。

排版惯例

在本文档的表格中,我们针对必需元素和可选元素使用以下惯例:

元素名称 必需元素
元素名称? 可选元素
元素名称* 可选元素,允许多个实例

元素和属性以标准 XPath 表示法表示。

联系人种类

表示联系人:人物、场所(例如俱乐部或餐馆)或组织。

类别元素:<atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#contact"/>

注意:如果您在 Contacts API 的上下文中使用联系人种类,请注意联系人 API 版本 2.0(在本文档中有所介绍)自 API API 3.0 版起使用。

属性

属性 说明
atom:category* 类别。系统会将具有 @label 属性的实例视为标记。如需了解如何使用 @scheme 属性,请参阅本部分开头的备注。
atom:content 联系人备注。
atom:link* 指向相关信息的链接。具体而言,atom:link[@rel='alternate'] 链接到描述联系人的 HTML 网页。
atom:title 联系人的姓名。此字段为只读字段。如需修改联系人的姓名,请参阅 gd:name
gd:email* 电子邮件地址。
gd:extendedProperty* 扩展属性。
gd:deleted 此元素的存在表示该联系人条目已被删除。
gd:im* IM 地址。
gd:name 结构化形式的联系人的姓名。
gd:organization* 整理作品。
gd:phoneNumber* 电话号码和传真号码。
gd:structuredPostalAddress* 联系人的邮寄地址(结构化格式)。
gd:where 与联系人关联的地点。

示例

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
  <category scheme='http://schemas.google.com/g/2005#kind' 
      term='http://schemas.google.com/contact/2008#contact'/>
  <title>Elizabeth Bennet</title>
  <content>My good friend, Liz.  A little quick to judge sometimes, but nice girl.</content>
  <gd:email rel='http://schemas.google.com/g/2005#work' primary='true' address='liz@gmail.com'/>
  <gd:email rel='http://schemas.google.com/g/2005#home' address='liz@example.org'/>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#work' primary='true'>
    (206)555-1212
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>
    (206)555-1213
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#mobile'>
    (206) 555-1212
  </gd:phoneNumber>
  <gd:im rel='http://schemas.google.com/g/2005#home' 
      protocol='http://schemas.google.com/g/2005#GOOGLE_TALK' 
      address='liz@gmail.com'/>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#work' primary='true'>
    1600 Amphitheatre Pkwy 
    Mountain View, CA 94043
  </gd:postalAddress>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#home'>
    800 Main Street
    Mountain View, CA 94041
  </gd:postalAddress>
  <gd:organization>
    <gd:orgName>Google, Inc.</gd:orgName>
    <gd:orgTitle>Tech Writer</gd:orgTitle>
  </gd:organization>
</entry>

个人资料种类

表示与 Google 用户或其他实体相关联的个人资料。个人资料种类与联系人种类有许多共同的结构。不过,也有一些差异:例如,它不能包含扩展属性或被标记为已删除。

类别元素:<atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#profile"/>

配置文件种类是在 3.0 版通讯录 API 中引入的。

属性

属性 说明
atom:category* 类别。系统会将具有 @label 属性的实例视为标记。如需了解如何使用 @scheme 属性,请参阅此部分开头的“类别元素”说明。
atom:content 关于该个人资料的备注。
atom:link* 指向相关信息的链接。具体而言,atom:link[@rel='alternate'] 链接到描述该配置文件的 HTML 网页。
atom:title 个人资料名称。此字段为只读字段。
gd:email* 电子邮件地址。
gd:im* IM 地址。
gd:name 名称(采用结构化格式)。
gd:organization* 整理作品。
gd:phoneNumber* 电话号码和传真号码。
gd:structuredPostalAddress* 邮政地址(采用结构化格式)。
gd:where 与商家资料相关联的地点。

示例

<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
  <category scheme='http://schemas.google.com/g/2005#kind'
  term='http://schemas.google.com/contact/2008#profile' />
  <title>Elizabeth Bennett</title>
  <gd:name>
    <gd:givenName>Elizabeth</gd:givenName>
    <gd:familyName>Bennett</gd:familyName>
  </gd:name>
  <gd:structuredPostalAddress rel='http://schemas.google.com/g/2005#work'>
    <gd:formattedAddress>Longbourne, Nr. Meryton, Hertfordshire, England</gd:formattedAddress>
  </gd:structuredPostalAddress>
</entry>

事件种类

表示日历活动。活动地点由 <gd:where> 元素中嵌入(或链接自)的联系人类型表示;活动策划者和参加者表示为嵌入(或链接自)<gd:who> 元素中的联系人种类。

类别元素:<category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>

属性

属性 说明
atom:author 创建此活动的人。
atom:category* 类别。系统会将具有 @label 属性的实例视为标记。如需了解如何使用 @scheme 属性,请参阅本部分开头的备注。
atom:content 对事件的详细说明。
atom:link* 链接。具体而言,atom:link[@rel='alternate'] 提供了指向用于描述事件的 HTML 网页的链接。
atom:title 活动的简要标题。
gd:comments 评论 Feed。
gd:eventStatus 可扩展的枚举如下所示。
gd:extendedProperty* 扩展属性。
gd:originalEvent 周期性活动的原始事件标识符。
gd:recurrence 重复规则。
gd:transparency 可扩展的枚举,与 RFC 2445 中定义的 TRANSP 属性相对应。
gd:visibility 可扩展的枚举如下所示。
gd:when* 活动时间。startTimeendTime 属性都必须设置,但对于全天事件,这些属性只是日期,而没有时间。
gd:when/gd:reminder* 活动提醒。
gd:where* 活动地点或附近场所(如停车场)。如果在 Feed 一级指定了 <gd:where> 元素,但条目一级没有 <gd:where> 元素,那么这些条目会继承 Feed 一级的 <gd:where> 值。
gd:who* 与活动相关的人员:组织者、参加者、演讲者和表演者等
gd:who/gd:attendeeStatus 接受状态。
gd:who/gd:attendeeType 参加者类型:requiredoptional

gd:where 的 rel 值

rel 值 说明
http://schemas.google.com/g/2005#event 或未指定。 活动举办地点。
http://schemas.google.com/g/2005#event.alternate 次要位置。例如,一个远程网站,包含指向主网站的视频会议链接。
http://schemas.google.com/g/2005#event.parking 附近的停车场。

gd:eventStatus 值

说明
http://schemas.google.com/g/2005#event.canceled 活动已取消。
http://schemas.google.com/g/2005#event.confirmed 活动按计划进行。
http://schemas.google.com/g/2005#event.tentative 活动只是临时举办的。

gd:Visibility 值

说明
http://schemas.google.com/g/2005#event.confidential 允许部分读者查看活动。
http://schemas.google.com/g/2005#event.default 继承活动所属日历所有者的偏好设置中的行为。
http://schemas.google.com/g/2005#event.private 仅允许最少量的读者查看活动。
http://schemas.google.com/g/2005#event.public 允许大多数读者查看活动。

gd:transparency 值

说明
http://schemas.google.com/g/2005#event.opaque 表明活动在日历上占用的时间;在有空/忙碌搜索中,活动时间将被标记为忙碌。
http://schemas.google.com/g/2005#event.transparent 表示活动在日历上没有任何时间使用;在有空/忙碌搜索中,活动时间不会标记为忙碌。

示例

会议:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Discuss BazMat API</title>
  <content>We will discuss integrating GData with BazMat.</content>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2005-01-18T21:00:00Z' endTime='2005-01-18T22:00:00Z'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where valueString='Building 41, Room X'/>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

线上活动:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/982307e797979879a</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Online Chess Tournament</title>
  <content/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2006-01-24T19:00:00-08:00' endTime='2006-01-24T20:00:00-08:00'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where>
    <gd:entryLink>
      <entry>
        <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
        <id>http://contacts.example.com/jo/GamePhannz</id>
        <published>2005-01-18T21:00:00Z</published>
        <updated>2006-01-01T00:00:00Z</updated>
        <title>GamePhannz Online Game Server</title>
        <link rel="http://schemas.google.com/g/2005#onlineLocation" type="text/html" href="http://gamephannz.example.com/chess/138fd87e"/>
        <content/>
      </entry>
    </gd:entryLink>
  </gd:where>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

消息种类

表示帖子,例如电子邮件、论坛帖子或评论。

类别元素:<atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>

属性

属性 说明
atom:category* 类别。系统会将具有 @label 属性的实例视为标记。如需了解如何使用 @scheme 属性,请参阅本部分开头的备注。如需了解如何使用 @term 属性,请参阅下表。
atom:content 邮件正文。
atom:link* 邮件附件。具体而言,如需上传附件,请使用 <link rel="enclosure"> 并将附件的内容放入 Atom 媒体集合中。
atom:title 邮件主题。
gd:geoPt 发布邮件的地理位置。
gd:rating 质量评分(由应用定义)。
gd:who* 与此消息相关的人员。确切的语义取决于 @rel 值。请参阅下表。

类别 @term 值

以下所有类别均采用 http://schemas.google.com/g/2005 架构。

术语 说明
http://schemas.google.com/g/2005#message.chat 消息是聊天会话的转录文本。
http://schemas.google.com/g/2005#message.inbox 相应邮件被标记为属于收件箱。
http://schemas.google.com/g/2005#message.sent 邮件已被标记为已发送。
http://schemas.google.com/g/2005#message.spam 相应邮件会被视为垃圾邮件。
http://schemas.google.com/g/2005#message.starred 邮件已标记为已加星标。
http://schemas.google.com/g/2005#message.unread 未读消息。

gd:who 的 rel 值

属性 说明
http://schemas.google.com/g/2005#message.bcc 邮件密送收件人。
http://schemas.google.com/g/2005#message.cc 邮件抄送收件人。
http://schemas.google.com/g/2005#message.from 邮件(电子邮件或即时通讯)发件人。
http://schemas.google.com/g/2005#message.reply-to 回复邮件的预期收件人。
http://schemas.google.com/g/2005#message.to 邮件主要收件人。

示例

电子邮件:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message.sent"/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <id>http://mymail.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2006-01-18T21:00:00Z</published>
  <updated>2006-01-18T21:00:00Z</updated>
  <title>Re: Info?</title>
  <content>Hi, Fritz -- The information you're looking for is on p. 47.</content>
  <gd:who rel="http://schemas.google.com/g/2005#message.from">
    <gd:entryLink href="http://contacts.example.com/jo/Jo"/>
  </gd:who>
  <gd:who rel="http://schemas.google.com/g/2005#message.to">
    <gd:entryLink href="http://contacts.example.com/fritzb/FritzB"/>
  </gd:who>
</entry>

Google 数据命名空间元素参考文档

本文档的其余部分包含这些种类所使用的元素的参考资料。

枚举

某些扩展元素需要指定其值来自枚举集的属性。此类属性的一般形式如下:

<gd:propertyName value="propertyValue">

如果属性值来自 Google 数据命名空间,则格式为 http://schemas.google.com/g/2005#{kind}.{value}。例如:http://schemas.google.com/g/2005#event.tentative。如果值空间可扩展,则值也可以采用 URI 的形式。建议将扩展值 URI 的格式设为 {schema URI}#{value}。例如:http://www.example.com/attendeeStatus#AudioConference

gEnumConstruct =
   attribute value { text },
   anyAttribute*

gdCommonProperties

适用于所有 Google 类型的通用属性。请注意,如果架构中存在 anyAttributeanyElement,则任何命名空间中进一步扩展使用通用属性的所有 Google 数据命名空间元素。尤其是,将任何 gd 元素或任何其他 Atom/RSS 元素嵌套在其他任何 gd 元素中都是合法的。此操作应谨慎进行,并且在大多数情况下,此类使用应记录为所包含 gd 元素类型的显式属性。

属性

属性 类型 说明
@xml:base uri 用于描述嵌套相对 URI 基础的标准 XML 结构。
@xml:lang text 嵌套字符串的语言。

架构

namespace gd = "http://schemas.google.com/g/2005"

gdCommonProperties = {
   atomCommonAttributes,
   anyAttribute*,
   (anyElement*)
}

gd:additionalName

指定用户的其他姓名(例如中间)。“Susan”。

属性

属性 类型 说明
@yomi xs:string 正向表示法。
text() xs:string 个人的姓氏。

示例

<gd:additionalName yomi="'suz@n">Susan<gd:additionalName>

架构

start = additionalName

additionalName =
   element gd:additionalName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:comments

包含所属条目的备注 Feed(如日历活动)。

属性

属性 类型 说明
@rel xs:string 所含评论的类型。目前,常规评论和评价是有区别的。
gd:feedLink feedLink 评论 Feed。此 Feed 应实现 Message 种类。

rel 值

说明
http://schemas.google.com/g/2005#regular 或未指定 定期评论(来自用户)。
http://schemas.google.com/g/2005#reviews 专业评价。

示例

评论 Feed:

<gd:comments>
  <gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

评价 Feed:

<gd:comments rel="http://schemas.google.com/g/2005#reviews">
  <gd:feedLink href="http://example.com/restaurants/SanFrancisco/432432/reviews" countHint="25">
    <feed>
      <id>http://example.com/restaurants/SanFrancisco/432432/reviews</id>
      <title>La Folie reviews</title>
      ...
      <entry>
         ...
         <content>Good food.</content>
         <gd:rating value="5" min="1" max="5"/>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

架构

start = comments

comments =
   element gd:comments {
      gdCommonProperties,
      attribute rel { xs:string }?,
      (feedLink?)
   }

gd:已删除

一个标记元素,如果存在,则表示包含的条目已被删除。

属性

无。

架构

start = deleted

deleted =
   element gd:deleted

gd:country

国家/地区名称和可选的国家/地区代码。后者遵循 ISO 3166-1 alpha-2 标准。

属性

属性 类型 说明
@code xs:string 国家/地区代码(采用 ISO 3166-1 alpha-2 格式)。
text() xs:string 国家/地区名称。

示例

<gd:country code='PL'>Poland</gd:country>
<gd:country>Gabon</gd:country>

架构

start = country

country =
   element gd:country {
      attribute code { xs:string }?,
      xs:string?
   }

gd:email

与所属实体(通常是代表某人员或某地点的实体)相关联的电子邮件地址。

属性

属性 类型 说明
@address xs:string 电子邮件地址。
@displayName xs:string 电子邮件地址所属实体(例如个人)的显示名称。
@label xs:string 用于为此电子邮件地址命名的简单字符串值。它允许界面显示“工作”、“个人”、“首选”等标签。
@rel xs:string 用于标识电子邮件类型的程序化值;如需了解详情,请参阅下文。
@primary xs:boolean 当某个联系人类型中出现多条电子邮件附加信息时,表明哪种是主要附加信息。最多只能有一个电子邮件地址作为主电子邮件地址。默认值为 "false"

rel 值

说明
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#other 既不是家用也非工作用的电子邮件地址。label 可用于指示实际类型。
http://schemas.google.com/g/2005#work

示例

<gd:email address="foo@bar.example.com" displayName="Foo Bar" />
<gd:email label="Personal" rel="http://schemas.google.com/g/2005#home" address="fubar@gmail.com" primary="true"/>

架构

start = email

email =
   element gd:email {
      attribute address { xs:string },
      attribute displayName { xs:string }?,
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?
   }

gd:entryLink

表示逻辑嵌套条目。例如,表示联系人的 <gd:who> 可能包含联系人 Feed 中的嵌套条目。

属性

属性 类型 说明
@href xs:string 指定条目 URI。如果嵌套条目是嵌入式且未关联的,则此属性可以省略。
@readOnly xs:boolean 指定所含条目是否为只读条目。默认值为 "false"
@rel xs:string 指定链接关系;允许该服务为单个实体提供多种类型的条目链接。与 <atom:link> 元素的 rel 属性具有相同的语义和允许的值。
atom:entry atomEntry 条目的内容。

限制

  • @href 和/或 <atom:entry> 必须存在。
  • 如果 atom:entry 不存在,客户端可以从 @href 中的条目 URI 提取内容。如果存在 atom:entry,则内容必须与生成条目时从 @href 检索到的内容相同。
  • 如果 PUTPOST 包含 <gd:entryLink> 且指定了 @href 属性,该属性的值将用于创建链接;如果 atom:entry 元素也存在,系统会忽略它。如果未指定 @href 属性,系统会将 atom:entry 元素存储为嵌入式条目,或将其存储在其他 Feed 中并与之关联。请注意,某些服务可能不支持所有这些选项。

示例

<gd:who>中的联系信息:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#contact"/>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </entry>
  </gd:entryLink>
</gd:who>

仅外部引用(只读条目):

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo" readOnly="true"/>
</gd:who>

架构

start = entryLink

entryLink =
   element gd:entryLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      (atomEntry?)
   }

gd:extendedProperty

允许将有限数量的自定义数据存储为封闭实体的辅助属性。

请注意,anyForeignElement 的存在允许 Feed 选择性地在 gd:extendedProperty 元素中嵌入任何有效的 XML(与 value 属性互斥)。

属性

属性 类型 说明
@name xs:string 指定以 URI 表示的属性名称。扩展属性 URI 通常遵循 {schema}#{local-name} 惯例。
@value xs:string 属性值。
@realm xs:string 供某些 API 用于指定扩展属性的应用位置。

示例

日历活动的外部标识符:

<gd:extendedProperty name="http://www.example.com/schemas/2007#mycal.id"
  value="1234"></gd:extendedProperty> 

联系人条目的其他 xml

<gd:extendedProperty name="com.google">
  <some_xml>value</some_xml>
</gd:extendedProperty>

架构

start = extendedProperty

extendedProperty =
   element gd:extendedProperty {
      attribute name { xs:string },
      attribute value { xs:string } ?,
      (anyForeignElement*),
      attribute realm { xs:string } ?
   }

gd:familyName

指定此人的姓氏,例如“Smith”。

属性

属性 类型 说明
@yomi xs:string 发音表示法。
text() xs:string 个人的姓氏。

示例

<gd:familyName yomi="smɪð">Smith<gd:familyName>

架构

start = familyName

familyName =
   element gd:familyName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:feedLink

表示逻辑嵌套的 Feed。例如,日历 Feed 可能有一个嵌套 Feed,代表条目的所有评论。

属性

属性 类型 说明
@countHint xs:unsignedInt 关于 Feed 中条目数的提示。根据实现情况,这可能不是精确计数。
@href xs:string 指定 Feed URI。如果嵌套 Feed 未链接,则此属性可省略。
@readOnly xs:boolean 指定所含 Feed 是否为只读。
@rel xs:string 指定链接关系;允许该服务为单个实体提供多种类型的 Feed 链接。与 <atom:link> 元素的 rel 属性具有相同的语义和允许的值。
atom:feed atomFeed Feed 的内容。

限制

  • @href 和/或 <atom:feed> 必须存在。
  • 如果 atom:feed 不存在,客户端可以从 @href 中的 URI 提取内容。如果存在,内容必须与在生成 Feed 时从 @href 检索到的内容相同。
  • 当 PUT 或 POST 包含 <gd:feedLink> 且指定了 @href 属性时,该属性的值将用于创建链接;如果 <atom:feed> 元素也存在,系统会忽略它。如果未指定 @href 属性,则系统会将 <atom:feed> 元素存储为嵌入式 Feed。请注意,某些服务可能不支持所有这些选项。

示例

博客:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>

仅外部参考:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments"
            countHint="10"/>

在代表列表的 Atom 条目中嵌入 Feed:

<gd:feedLink>
  <feed>
    <id>cid:1</id>
    <entry>
       <id>cid:1.1</id>
       <content>list item 1</content>
    </entry>
    <entry>
       <id>cid:1.2</id>
       <content>list item 2</content>
    </entry>
  </feed>
</gd:feedLink>

架构

start = feedLink

feedLink =
   element gd:feedLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      attribute countHint { xs:unsignedInt }?,
      (atomFeed?)
   }

gd:geoPt

地理位置(纬度、经度、海拔)。

已弃用。此元素已弃用。对于地理标记数据,请改用 GeoRSS

属性

属性 类型 说明
@elev xs:float 海拔(以米为单位)。负值表示低于平均水平的深度。
@label xs:string 用于命名此位置的简单字符串值。它允许界面显示“当前位置”等标签。
@lat xs:float 纬度(以度为单位)。正值表示北,负值表示南。范围为 [-90.0, 90.0]。
@lon xs:float 经度(以度为单位)。正值表示东方,负值表示西方。范围为 [-180.0, 180.0]。
@time xs:dateTime 时间戳。

示例

<gd:geoPt lat="40.75" lon="-74.0"/>
<gd:geoPt lat="27.98778" lon="86.94444" elev="8850.0"/>

架构

start = geoPt

geoPt =
   element gd:geoPt {
      attribute label { xs:string }?,
      attribute lat { xs:float },
      attribute lon { xs:float },
      attribute elev { xs:float }?,
      attribute time { xs:dateTime }?
   }

GD:IM

与包含的实体关联的即时通讯地址。

属性

属性 类型 说明
@address xs:string IM 地址。
@label xs:string 用于命名此 IM 地址的简单字符串值。它允许界面显示“工作”、“个人”、“首选”等标签。
@rel xs:string 用于标识 IM 类型的程序化值;有关详情,请参见下文。
@protocol xs:string 用于标识 IM 网络。该值可以是标准值之一(如下所示),也可以是用于标识专有 IM 网络的 URI。
@primary xs:boolean 当某个联系人类型中出现多个 IM 附加信息时,表明哪种是主要信息。最多只能有 1 条即时通讯作为主要聊天方式。默认值为 "false"

rel 值

说明
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#netmeeting
http://schemas.google.com/g/2005#other 既不是家也不是单位的 IM 地址。label 可用于指示实际类型。
http://schemas.google.com/g/2005#work

协议属性值

下表显示了 @protocol 属性的一些可能值。

说明
http://schemas.google.com/g/2005#AIM AOL Instant Messenger 协议
http://schemas.google.com/g/2005#MSN MSN Messenger 协议
http://schemas.google.com/g/2005#YAHOO Yahoo Messenger 协议
http://schemas.google.com/g/2005#SKYPE Skype 协议
http://schemas.google.com/g/2005#QQ QQ 协议
http://schemas.google.com/g/2005#GOOGLE_TALK Google Talk 协议
http://schemas.google.com/g/2005#ICQ ICQ 协议
http://schemas.google.com/g/2005#JABBER Jabber 协议

示例

MSN Messenger 的即时通讯地址:

<gd:im protocol="http://schemas.google.com/g/2005#MSN" address="foo@bar.msn.com" rel="http://schemas.google.com/g/2005#home" primary="true"/>

用户提供的采用未指定协议的 IM 地址。此类地址对于显示很有用,但以编程方式难以处理。

<gd:im label="Other" address="foo@baz.example.com"/>

架构

start = im

im =
   element gd:im {
      attribute address { xs:string },
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute protocol { xs:string }?,
      attribute primary { xs:boolean }?
   }

gd:名字

指定人员的名字,例如“John”。

属性

属性 类型 说明
@yomi xs:string 发音表示法。
text() xs:string 个人的名字。

示例

<gd:givenName yomi="dʒon">John<gd:givenName>

架构

start = givenName

givenName =
   element gd:givenName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:money

指定以特定货币为单位的金额。

属性

属性 类型 说明
@amount xsd:float 金额。
@currencyCode xsd:string ISO4217 货币代码。

示例

<gd:money amount='650.0' currencyCode='EUR'/>

架构

element gd:money {
  attribute amount { xsd:float },
  attribute currencyCode { xsd:string }
}

gd:name

允许以结构化方式存储用户的姓名。包括名字、额外名称、姓氏、前缀、后缀全名

属性

属性 类型 说明
gd:givenName givenName 个人的名字。
gd:additionalName additionalName 人物的其他名称,例如中间名。
gd:familyName familyName 个人的姓氏。
gd:namePrefix namePrefix 名称前缀,例如“Mr”或“Mrs”。
gd:nameSuffix nameSuffix 提供后缀,例如“san”或“III”。
gd:fullName fullName 非结构化名称。

示例

KG Winston Leonard Spencer-Churchill 爵士的结构化表示

<gd:name>
  <gd:givenName>Winston</gd:givenName>
  <gd:additionalName>Leonard</gd:additionalName>
  <gd:familyName>Spencer-Churchill</gd:familyName>
  <gd:namePrefix>Sir</gd:namePrefix>
  <gd:nameSuffix>OG</gd:nameSuffix>
</gd:name>

架构

start = name

name =
   element gd:name {
      givenName?
      & additionalName?
      & familyName?
      & namePrefix?
      & nameSuffix?
   }

限制

  • 名称的非结构化组件应与其结构化表示法保持一致。

gd:organization

通常与联系人关联的组织。

属性

属性 类型 说明
@label xs:string 用于为此组织命名的简单字符串值。该页面允许界面显示“工作”、“志愿者”、“专业协会”等标签。
gd:orgDepartment orgDepartment 指定组织内的一个部门。
gd:orgJobDescription orgJobDescription 组织内的职位说明。
gd:orgName orgName 机构的名称。
gd:orgSymbol orgSymbol 组织的标志。
gd:orgTitle orgTitle 组织内人员的职位。
@primary xs:boolean 当某个联系人类型中出现多个组织部门时,表明是哪个组织部门。最多只能有一个组织是主要组织。默认值为 "false"
@rel xs:string 用于标识组织类型的程序化值;如需了解详情,请参阅下文。
gd:where where 与组织关联的地点,例如办公地点。

rel 值

说明
http://schemas.google.com/g/2005#other 组织无效。label 可用于指示实际类型。
http://schemas.google.com/g/2005#work

示例

<gd:organization rel="http://schemas.google.com/g/2005#work" label="Work" primary="true">
  <gd:orgName>Google, Inc.</gd:orgName>
  <gd:orgTitle>Tech Writer</gd:orgTitle>
  <gd:orgJobDescription>Writes documentation</gd:orgJobDescription>
  <gd:orgDepartment>Software Development</gd:orgDepartment>
  <gd:orgSymbol>GOOG</gd:orgSymbol>
</gd:organization>

架构

start = organization

organization =
   element gd:organization {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      ( orgDepartment? &
      orgJobDescription? &
      orgName? &
      orgSymbol? &
      orgTitle? &
      where? )
   }

gd:org 部

描述组织内的某个部门。必须出现在 gd:organization 元素中。

示例

<gd:orgDepartment>Research and Development</gd:orgDepartment>

架构

start = orgDepartment

orgDepartment = element gd:orgDepartment { xs:string }

gd:orgJobDescription

描述组织中的作业。必须出现在 gd:organization 元素中。

示例

<gd:orgJobDescription>Documenting public APIs</gd:orgJobDescription>

架构

start = orgJobDescription

orgJobDescription = element gd:orgJobDescription { xs:string }

gd:orgName

组织的名称。必须出现在 gd:organization 元素中。

属性

属性 说明
@yomi 代表单位名称的 Yomigana(日语辅助工具)。

示例

<gd:orgName>Google, Inc.</gd:orgName>

架构

start = orgName

orgName =
   element gd:orgName {
     attribute yomi {xs:string},
     xs:string
   }

gd:orgSymbol

提供组织的符号。必须出现在 gd:organization 元素中。

示例

<gd:orgSymbol>GOOG</gd:orgSymbol>

架构

start = orgSymbol

orgSymbol = element gd:orgSymbol { xs:string }

gd:orgTitle

组织内人员的名称。必须出现在 gd:organization 元素中。

示例

<gd:orgTitle>President and CEO</gd:orgTitle>

架构

start = orgTitle

orgTitle =
   element gd:orgTitle { xs:string }

gd:OriginalEvent

相当于 RFC 2445 第 4.8.4.4 节中指定的重复周期 ID 属性。显示在周期性活动的每个实例中,用于标识原始活动。

包含 <gd:when> 元素,该元素指定实例已成为异常的原始开始时间。

属性

属性 类型 说明
@id xs:string 原始事件的事件 ID。
@href xs:string 原始事件的事件 Feed 网址。

示例

指定原始事件:

<gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"

href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID">
  <gd:when startTime="2006-03-17T22:00:00.000Z"/>
</gd:originalEvent>

架构

start = originalEvent

originalEvent =
   element gd:originalEvent {
      attribute id { xs:string },
      attribute href { xs:string },
      when
   }

gd:phoneNumber

与所含实体(通常是代表某人员或某地点的实体)相关联的电话号码。

属性

属性 类型 说明
@label xs:string 用于为此电话号码命名的简单字符串值。在大多数情况下,@label 不是必要的,因为 @rel 可唯一标识某个数字,并允许界面显示适当的标签(如“手机”、“家庭”、“工作”等)。不过,例如,如果一个用户拥有多个手机,此属性就可用于消除歧义。
@rel xs:string 用于标识电话号码类型的程序化值;如需了解详情,请参阅下文。
@uri xs:string 可选用“tel URI”表示,以正式方式表示号码,对编程访问非常有用,例如 VoIP/PSTN 网桥。如需详细了解 tel URI,请参阅 RFC 3966
@primary xs:boolean 当某个联系人类型中包含多个电话号码附加信息时,表明哪个是主要电话号码。最多只能指定一个电话号码。默认值为 "false"
text() xs:string 简单易懂的电话号码;可以使用任何电话号码格式。前导和尾随空格无关紧要。字符串中的换行符也无关紧要,并且可以移除或展平到一个空格。

rel 值

说明
http://schemas.google.com/g/2005#assistant
http://schemas.google.com/g/2005#callback
http://schemas.google.com/g/2005#car
http://schemas.google.com/g/2005#company_main
http://schemas.google.com/g/2005#fax
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#home_fax
http://schemas.google.com/g/2005#isdn
http://schemas.google.com/g/2005#main
http://schemas.google.com/g/2005#mobile
http://schemas.google.com/g/2005#other 特殊类型的数字,其他 rel 值均不适用。label 可用于指示实际类型。
http://schemas.google.com/g/2005#other_fax
http://schemas.google.com/g/2005#pager
http://schemas.google.com/g/2005#radio
http://schemas.google.com/g/2005#telex
http://schemas.google.com/g/2005#tty_tdd
http://schemas.google.com/g/2005#work
http://schemas.google.com/g/2005#work_fax
http://schemas.google.com/g/2005#work_mobile
http://schemas.google.com/g/2005#work_pager

示例

用户输入的简单电话号码:

<gd:phoneNumber>(425) 555-8080 ext. 72585</gd:phoneNumber>

从目录中提取的电话号码相同:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#work" uri="tel:+1-425-555-8080;ext=52585">
  (425) 555-8080 ext. 52585
</gd:phoneNumber>

带标签的数字:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#mobile" label="Personal calls only" uri="tel:+12065551212">
  +1 206 555 1212
</gd:phoneNumber>

架构

start = phoneNumber

phoneNumber =
   element gd:phoneNumber {
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute uri { xs:string }?,
      attribute primary { xs:boolean }?,
      (xs:string)
   }

gd:postalAddress

邮政地址。

属性

属性 类型 说明
@label xs:string 用于为此地址命名的简单字符串值。
@rel xs:string 用于标识邮政地址类型的程序化值;如需了解详情,请参阅下文。
@primary xs:boolean 当某个联系人类型中出现多个邮政地址扩展时,指示哪个是主要地址。最多只能有一个邮政地址是主要地址。默认值为 "false"
text() xs:string 以文本形式表示的地址。前导和尾随空格无关紧要。字符串内的换行符很重要。

rel 值

说明
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#other 既不是家也不是单位的地址。label 可用于指示实际类型。
http://schemas.google.com/g/2005#work

示例

<gd:postalAddress>
  500 West 45th Street
  New York, NY 10036
</gd:postalAddress>

架构

start = postalAddress

postalAddress =
   element gd:postalAddress {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      (xs:string)
   }

gd:rating

表示所属实体(例如评论)的数字评分。尽管每个服务都可以对其进行标准化,但每个服务都会提供自己的评分量表;例如,某些服务可以将所有评分转换为 1 到 5 之间的评分值。

属性

属性 类型 说明
@average xs:float 平均评分。
@max xs:int 评分等级的最大值。
@min xs:int 评分量表的最小值。
@numRaters xs:int 计算平均值时考虑的评分数量。
@rel xs:string 指定评分时的评分。如果未指定,则评分为总体评分。
@value xs:int 评分值。

rel 值

说明
http://schemas.google.com/g/2005#overall 或未指定 总体评分。值越高,评分越高。
http://schemas.google.com/g/2005#price 价格评分。值越高,价格越高。
http://schemas.google.com/g/2005#quality 质量评分。值越高,画质越高。

示例

4/5 评分:

<gd:rating value="4" min="1" max="5"/>

最昂贵的价格范围评分:

<gd:rating rel="http://schemas.google.com/g/2005#price" value="5" min="1" max="5"/>

200 位用户平均给出 4.65 分(满分为 5 分):

<gd:rating average="4.65" min="1" max="5" numRaters="200"/>

架构

start = rating

rating =
   element gd:rating {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute value { xs:int }?,
      attribute average { xs:float }?,
      attribute min { xs:int },
      attribute max { xs:int },
      attribute numRaters { xs:int }?
   }

gd:重复周期

表示周期性活动发生的日期和时间。

定义重复规则的字符串由一组属性构成,每个属性在 iCalendar 标准 (RFC 2445) 中定义。

具体而言,字符串通常以表示事件首次实例的开始时间的 DTSTART 属性开头,通常以表示第一个实例何时结束的 DTEND 属性或 DURATION 属性开头。接下来是 RRULE、RDATE、EXRULE 和/或 EXDATE 属性,它们共同定义了周期性活动及其例外情况(请参阅下文)。(如需详细了解这些重复周期属性,请参阅 RFC 2445 第 4.8.5 节。)最后是 VTIMEZONE 组件,为上述属性中提及的任何时区 ID 提供详细的时区规则。

Google 日历等 Google 服务一般不会生成 EXRULE 和 EXDATE 属性来表示周期性活动的例外情况,而是会生成 <gd:recurrenceException> 元素。不过,Google 服务可能仍会包含 EXRULE 和/或 EXDATE 属性;例如,用户可以将活动和例外情况导入到 Google 日历,而且如果这些导入的活动包含 EXRULE 或 EXDATE 属性,那么 Google 日历会在发送 <gd:recurrence> 元素时提供这些属性。

请注意,使用 <gd:recurrenceException> 意味着您不能仅通过检查 <gd:recurrence> 元素来确认重复说明是否有任何例外情况。为确保找出所有例外情况,请在 Feed 中查找 <gd:recurrenceException> 元素,并使用其 <gd:originalEvent> 元素将其与 <gd:recurrence> 元素相匹配。

属性

属性 类型 说明
text() xs:string 重新生成说明。

示例

周期性活动每天上午 6:00 至 7:00太平洋时间(2006 年 3 月 14 日至 3 月 21 日):

<gd:recurrence>
  DTSTART;TZID=America/Los_Angeles:20060314T060000
  DURATION:PT3600S
  RRULE:FREQ=DAILY;UNTIL=20060321T220000Z
  BEGIN:VTIMEZONE
  TZID:America/Los_Angeles
  X-LIC-LOCATION:America/Los_Angeles
  BEGIN:STANDARD
  TZOFFSETFROM:-0700
  TZOFFSETTO:-0800
  TZNAME:PST
  DTSTART:19671029T020000
  RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
  END:STANDARD
  BEGIN:DAYLIGHT
  TZOFFSETFROM:-0800
  TZOFFSETTO:-0700
  TZNAME:PDT
  DTSTART:19870405T020000
  RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU
  END:DAYLIGHT
  END:VTIMEZONE
</gd:recurrence>

架构

start = recurrence

recurrence =
   element gd:recurrence {
      (xs:string)
   }

gd:recurrenceException

表示周期性活动(即周期性活动中一个或多个活动方面(例如出席列表、时间或地点)发生了变化)的实例。

包含一个 <gd:originalEvent> 元素,该元素指定了此事件作为例外的原始周期性事件。

如果您更改周期性活动的实例,则该实例会变为异常。根据您对它所做的更改,当原始周期性活动发生更改时,异常会以以下两种不同方式运作:

  • 如果您添加、更改或移除评论、参加者或参加者回复,则该例外情况仍与原始活动相关联,并且对原始活动所做的更改也会改变该例外情况。
  • 如果您对异常进行任何其他更改(例如更改时间或地点),则该实例将变为“特殊”状态,这意味着该实例将不再与原始事件紧密相关。如果您更改原始活动,专门的例外情况不会改变。但请参见下文。

例如,假设您在每周二和周四的下午 2:00 都有会议,但如果您更改此星期四的会议的出席情况列表(而不是常规会议的会议列表),则会议例外。如果您更改了本周四的会议时间(而不是定期安排的会议时间),那么会议就会变得专业化。

无论异常是否专业化,如果您执行了某项操作以删除作为其源自的异常的实例,则会删除该异常。请注意,更改周期性活动的日期或时间会删除所有实例,并创建新实例。

例如,专门安排了星期四的会议后,您可以将周期性会议的开始时间改为星期一、星期三和星期五。这项更改会删除周二/周四会议的所有周期性活动,包括专门的会议。

如果周期性活动的特定实例被删除,则该实例将显示为包含 <gd:entryLink>(其 <gd:eventStatus> 设置为 "http://schemas.google.com/g/2005#event.canceled")的 <gd:recurrenceException>。(有关已取消事件的详细信息,请参阅 RFC 2445。)

属性

属性 类型 说明
@specialized xs:boolean 指明异常是否较为特殊。
gd:entryLink entryLink 事件详情,提供有关异常的详细信息。
gd:originalEvent originalEvent 此原始周期性活动是例外。

示例

周期性活动的例外情况(为清楚起见,用简单的斜体标识符替换部分片段):

<gd:recurrenceException specialized="true">
  <gd:entryLink>
    <entry>
      <id>i8fl1nrv2bl57c1qgr3f0onmgg_20060317T220000Z</id>
      <published>2006-03-17T23:00:00.000Z</published>
      <updated>2006-03-14T21:33:12.000Z</updated>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#event"/>
      <title type="text">recurrence</title>
      <content type="text"/>
      <link rel="alternate" type="text/html"
        href="http://www.google.com/calendar/event?eid=idString"
        title="alternate"/>
      <author>
        <name>exception</name>
      </author>
      <gd:eventStatus
        value="http://schemas.google.com/g/2005#event.confirmed"/>
      <gd:comments>
        <gd:feedLink
            href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/">
          <feed>
            <updated>2006-03-14T21:36:23.250Z</updated>
            <title type="text">Comments for: recurrence</title>
            <link rel="alternate" type="text/html"
              href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/"
              title="alternate"/>
          </feed>
        </gd:feedLink>
      </gd:comments>
      <gd:transparency
        value="http://schemas.google.com/g/2005#event.opaque "/>
      <gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"
          href="http://www.google.com/calendar/feeds/userID/private-magicCookie/composite/eventID">
        <gd:when startTime="2006-03-17T22:00:00.000Z"/>
      </gd:originalEvent>
      <gd:where valueString="Home"/>
      <gd:when startTime="2006-03-17T23:00:00.000Z"
        endTime="2006-03-18T00:00:00.000Z"/>
    </entry>
  </gd:entryLink>
</gd:recurrenceException>

架构

start = recurrenceException

recurrenceException =
   element gd:recurrenceException {
      attribute specialized { xs:boolean },
      (entryLink
       & originalEvent)
   }

gd:提醒

最常用于:<gd:when>

时间间隔,用于指明应在多久后发出包含实体的 @startTime@dueTime 属性。或者,可以指定发出提醒的绝对时间。还指定了通知方法,指示系统应使用何种媒介来提醒用户。

属性

属性 类型 说明
@absoluteTime xs:dateTime 发出提醒的绝对时间。这通常在用户使用“暂停”功能来延迟以前的提醒时使用。如果未指定时区,则采用观察者的本地时间。
@method xs:string 提醒应使用的通知方法。可具有以下任意值:alert(导致用户在浏览器中查看日历时显示提醒)、email(向用户发送电子邮件)或 sms(向用户发送短信)。
@days xs:unsignedInt gd:when/@startTime 之前应发出提醒的时间段。如果父实体的目标时间是日期,而不是特定时间,则这些属性相对于该日期的午夜 (00:00)。
@hours xs:unsignedInt
@minutes xs:unsignedInt

创建或修改 <gd:when> 条目时,请遵循以下约定来实现特定结果:

  • 如需告知服务使用用户的默认提醒,请添加一个不带属性的 <gd:reminder> 元素。如果您指定了时长,但没有指定 method 属性,该服务会使用用户的默认通知方法,并指定该时长。
  • 要让该服务不要针对任何活动发出提醒(或在更新活动时移除现有提醒),请勿添加任何 <gd:reminder> 元素。

限制

  • 最多只能指定 @days@hours@minutes@absoluteTime。要指定混合时长,请转换为最精确的单位。例如,如需指定 1 小时 30 分钟,请使用 @minutes="90"
  • 您不能为属性使用负值(因此,如果您希望提醒在开始时间之后发生,则必须使用 @absoluteTime)。
  • 与给定活动关联的提醒数量不能超过五个。
  • 向活动添加提醒时,如果您指定 alertemailsms 方法,还必须指定时长。

示例

为会议设置 15 分钟的提醒:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
</gd:when>

与上述会议相同,但在提醒 16:45 后延后了 10 分钟:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
  <gd:reminder absoluteTime="2005-06-06T16:55:00-08:00"/>
</gd:when>

架构

start = reminder

reminder =
   element gd:reminder {
      gdCommonProperties,
      attribute absoluteTime { xs:dateTime }?,
      attribute method { xs:string }?,
      attribute days { xs:unsignedInt }?,
      attribute hours { xs:unsignedInt }?,
      attribute minutes { xs:unsignedInt }?
   }

gd:resourceId

不透明资源标识符,与 atom:id 不同,因为它不需要是有效的 URI。某些服务提供单独的标识符,以供在构建后续请求时使用。确切用量因服务而异。

示例

<gd:resourceId>9749638</gd:resourceId>

架构

start = resourceId

resourceId =
   element gd:resourceId { xs:string }

gd:结构化邮政地址

将邮寄地址拆分成多个部分。它允许以独立于语言区域的格式存储地址。这些字段可解释为用来生成带格式的语言区域相关地址。以下元素是地址的组成部分:代理、房屋名称、街道、邮政信箱、街区、城市、子区域、区域、邮政编码、国家/地区subregion 元素不用于邮政地址,仅用于地址的扩展用途。为了以非结构化形式存储邮政地址,我们提供格式化地址字段。

属性

属性 类型 说明
@rel xs:string 地址类型。除非指定 work 类型。
@mailClass xs:string 地址中接受的邮件类别。除非指定 both
@usage xs:string 此添加者可以使用的上下文。本地地址的布局可能与一般地址不同,而且经常使用本地脚本(而不是拉丁字母),尽管常规地址中允许使用本地脚本。除非已指定 general 用法。
@label xs:string 地址的常规标签。
@primary xs:boolean 将地址指定为主要地址。默认值为 false
gd:agent agent 实际接收邮件的代理。在工作地址中使用。也用于“转交”或“c/o”。
gd:housename housename 在房屋或建筑物有名称(不一定是数字)的地方使用,例如,“柱子”。
gd:street street 可以是街道、大道、道路等。此元素还包含门牌号和房间/公寓/楼号/楼层号。
gd:pobox pobox 涵盖真实的邮政信箱、抽屉、锁袋等。这通常并非与街道互斥。
gd:neighborhood neighborhood 当城市中包含多条同名的街道时,此属性用于消除歧义地址,或指定其邮件通过某个更大的邮政城镇时所在的小型地点。在中国,国家/地区可以是县或城市。
gd:city city 可以是市、村、镇、自治市等。这是邮政镇,而不一定是居住地或办公地点。
gd:subregion subregion 处理不用于邮寄地址处理的美国学区或英国学区。次级区域不适用于配送地址。
gd:region region 州、省、郡(爱尔兰)、土地(德国)、省(在法国)等
gd:postcode postcode 邮政编码。通常为国家/地区范围,但有时针对特定的城市(例如,“都柏林 2,爱尔兰”中的地址为“2”)。
gd:country country 国家/地区的名称或代码。
gd:formattedAddress formattedAddress 完整的非结构化邮政地址。

rel 值

说明
http://schemas.google.com/g/2005#work 单位地址。除非另有提供,否则该值均为默认值。
http://schemas.google.com/g/2005#home 家庭住址。
http://schemas.google.com/g/2005#other 任何其他类型的地址。

mailClass 值

说明
http://schemas.google.com/g/2005#both 地块和字母可发送至该地址。除非另有提供,否则该值均为默认值。
http://schemas.google.com/g/2005#letters 只能向该地址发送字母。
http://schemas.google.com/g/2005#parcels 只能向该地址发送包裹。
http://schemas.google.com/g/2005#neither 地址只用于提供位置信息,不能用于发送邮件。

用量值

说明
http://schemas.google.com/g/2005#general 此地址供一般用途使用。除非另有提供,否则该值均为默认值。
http://schemas.google.com/g/2005#local 此地址供本地使用,

示例

公司地址:

John Doe
Google Inc.
1600 Amphitheatre Parkway
Mountain View, CA 94043
<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#letters' label='John at Google'>
  <gd:street>1600 Amphitheatre Parkway</gd:street>
  <gd:city>Mountain View</gd:city>
  <gd:region>CA</gd:region>
  <gd:postcode>94043</gd:postcode>
</gd:structuredPostalAddress>

私人网址:

Duame Duval
27, rue Pasteur
14390 CABOURG
法国
<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#both' label='Madame Duval'>
  <gd:street>27, rue Pasteur</gd:street>
  <gd:city>CABOURG</gd:city>
  <gd:postcode>14390</gd:postcode>
  <gd:country>FRANCE</gd:country>
</gd:structuredPostalAddress>

架构

start = structuredPostalAddress

structuredPostalAddress =
   element gd:structuredPostalAddress {
      attribute label { xs:string }?,
      attribute mailClass { xs:string }?,
      attribute primary { xs:boolean }?,
      attribute rel { xs:string }?,
      attribute usage { xs:string }?,
      (agent?
       & housename?
       & street?
       & poBox?
       & neighborhood?
       & city?
       & subregion?
       & region?
       & postcode?
       & country?
       & formattedAddress? )
}

限制

  • 严禁在一个实体中同时存在“gd:postalAddress”和“gd:结构化邮政地址”。
  • 只能指定一个结构化地址作为主要地址。
  • 非结构化邮政地址必须与结构化数据一致。

gd:when

表示一段时间或某个时刻。

属性

属性 类型 说明
@endTime xs:dateTimexs:date 描述活动何时结束。如果未指定时区,则采用观察者的本地时区。
@startTime xs:dateTimexs:date 描述活动何时开始或何时发生(对于零持续时间活动)。如果未指定时区,则采用观察者的本地时区。
@valueString xs:string 一个简单的字符串值,可用作此时间段的表示法。

限制

  • 无法在 startTime/endTime 中混用 xs:dateTimexs:date
  • 如果未指定 endTime,则该事件将被视为即时(如果 @startTime 包含时间)或一天事件(如果 @startTime 只是日期)。

示例

为期一天的活动:

<gd:when startTime="2005-06-06"/>

为期一天的活动的替代表示:

<gd:when startTime="2005-06-06" endTime="2005-06-07"/>

为期两天的活动(6 月 6 日和 6 月 7 日),包含字符串说明:

<gd:when startTime="2005-06-06" endTime="2005-06-08" valueString="This weekend"/>

一小时会议:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00"/>

持续时间为零的活动:

<gd:when startTime="2005-06-06T17:00:00-08:00"/>

架构

start = when

when =
   element gd:when {
      gdCommonProperties,
      attribute startTime { (xs:date | xs:dateTime) },
      attribute endTime { (xs:date | xs:dateTime) }?,
      attribute valueString { xs:string }?
   }

gd:where

与所含实体关联的地点(例如活动地点)。关联类型由 rel 属性决定;位置的详情包含在嵌入式或关联的联系人条目中。

<gd:where> 元素比 <gd:geoPt> 元素更通用。前者使用文本描述和/或联系人条目标识地点,而后者使用特定的地理位置来标识地点。

属性

属性 类型 说明
@label xs:string 指定用户可读的标签,以便将此营业地点与其他营业地点区分开来。
@rel xs:string 指定所含实体与包含的位置之间的关系。可能的值(见下文)由其他元素定义。例如,<gd:when> 定义了 http://schemas.google.com/g/2005#event
@valueString xs:string 可用作此位置表示法的简单字符串值。
gd:entryLink entryLink 代表营业地点详情的条目。此条目应实现 Contact 种类。

rel 值

说明
http://schemas.google.com/g/2005#event 或未指定 发生封闭事件的位置。
http://schemas.google.com/g/2005#event.alternate 次要位置。例如,一个远程网站,包含指向主网站的视频会议链接。
http://schemas.google.com/g/2005#event.parking 附近的停车场。

示例

活动地点:

<gd:where valueString="Google Cafeteria (Building 40)"/>

更复杂的活动地点:

<gd:where rel="http://schemas.google.com/g/2005#event" valueString="Joe's Pub">
  <gd:entryLink href="http://local.example.com/10018/JoesPub">
    <gd:entry>
      <id>http://local.example.com/10018/JoesPub</id>
      <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
      <content>Nice place to listen to jazz music</content>
      <link href="http://www.joespub.com"/>
      <gd:postalAddress>500 West 45th Street, New York, NY 10018</gd:postalAddress>
      <gd:geoPt lat="40.75" lon="-74.0"/>
      <gd:phoneNumber>(212) 555-1212</gd:phoneNumber>
      <gd:email address="info@joespub.com"/>
    </gd:entry>
  </gd:entryLink>
</gd:where>

包含多个地点的活动:

<gd:where label="Mountain View Location (main)"
         valueString="Google Cafeteria (Building 40)"/>

<gd:where rel="http://schemas.google.com/g/2005#event.alternate"
         label="New York Location (videoconference)"
         valueString="Metropolis"/>

架构

start = where

where =
   element gd:where {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute valueString { xs:string }?,
      (entryLink?)
   }

gd:谁

与所包含实体相关联的人员。关联类型由 rel 属性确定;有关个人的详细信息包含在嵌入或链接到的联系人条目中。

<gd:who> 元素可用于指定电子邮件发件人和收件人、日历活动组织者等。

属性

属性 类型 说明
@email xs:string 电子邮件地址。如果未指定 <gd:entryLink>,则通常使用此属性。该地址必须符合 RFC 2822 第 3.4.1 节的规定。
@rel xs:string 指定所含实体与所包含人员之间的关系。如需了解可能的值,请参阅下文。
@valueString xs:string 简单的字符串值,可代表此人。
gd:attendeeStatus gEnumConstruct 活动参加者的状态。可扩展的枚举如下所示。
gd:attendeeType gEnumConstruct 活动参加者的类型。可扩展的枚举如下所示。
gd:entryLink entryLink 代表个人详细信息的条目。此条目应实现 Contact 种类。在许多情况下,此条目来自联系人 Feed。

rel 值

@rel 的有效值取决于 <gd:who> 元素的类型。

种类 说明
http://schemas.google.com/g/2005#event.attendee 活动 一般会议/活动参加者。
http://schemas.google.com/g/2005#event.organizer 活动 活动组织者。组织者不一定是参加者。
http://schemas.google.com/g/2005#event.performer 活动 表演者。类似于 http://schemas.google.com/g/2005#event.speaker,但更侧重于艺术,而不是语音传递。
http://schemas.google.com/g/2005#event.speaker 活动 扬声器。
http://schemas.google.com/g/2005#message.bcc 消息 邮件密送收件人。
http://schemas.google.com/g/2005#message.cc 消息 邮件抄送收件人。
http://schemas.google.com/g/2005#message.from 消息 邮件(电子邮件或即时通讯)发件人。
http://schemas.google.com/g/2005#message.reply-to 消息 回复邮件的预期收件人。
http://schemas.google.com/g/2005#message.to 消息 邮件主要收件人。

gd:attendeeType 值

说明
http://schemas.google.com/g/2005#event.optional 可选的参加者。
http://schemas.google.com/g/2005#event.required 需要参加者。

gd:attendeeStatus 值

说明
http://schemas.google.com/g/2005#event.accepted 参加者已接受。
http://schemas.google.com/g/2005#event.declined 参加者已拒绝。
http://schemas.google.com/g/2005#event.invited 已发送邀请,但对方尚未接受。
http://schemas.google.com/g/2005#event.tentative 参加者已暂时接受。

示例

电子邮件收件人:

<gd:who rel="http://schemas.google.com/g/2005#message.from" email="jo@example.com"/>
<gd:who rel="http://schemas.google.com/g/2005#message.to" valueString="Elizabeth" email="liz@example.com"/>

会议参加者:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:attendeeType value="http://schemas.google.com/g/2005#event.required"/>
  <gd:attendeeStatus value="http://schemas.google.com/g/2005#event.tentative"/>
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </entry>
  </gd:entryLink>
</gd:who>

活动组织者:

<gd:who rel="http://schemas.google.com/g/2005#event.organizer" valueString="Receptionist 41"/>

架构

start = who

who =
   element gd:who {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute email { xs:string }?,
      attribute valueString { xs:string }?,
      (entryLink?
       & element gd:attendeeType { gEnumConstruct }?
       & element gd:attendeeStatus { gEnumConstruct }?)
   }

返回页首

自 1.0 以来的更改

对联系人种类的更改

版本 2.0 中添加了未存在于版本 1.0 中的以下元素:

2.0 版中添加了 1.0 版中不存在的以下电话类型

  • http://schemas.google.com/g/2005#assistant
  • http://schemas.google.com/g/2005#callback
  • http://schemas.google.com/g/2005#car
  • http://schemas.google.com/g/2005#company_main
  • http://schemas.google.com/g/2005#isdn
  • http://schemas.google.com/g/2005#main
  • http://schemas.google.com/g/2005#other_fax
  • http://schemas.google.com/g/2005#radio
  • http://schemas.google.com/g/2005#telex
  • http://schemas.google.com/g/2005#tty_tdd
  • http://schemas.google.com/g/2005#work_mobile
  • http://schemas.google.com/g/2005#work_pager

2.0 版中添加了 1.0 版中不存在的以下 IM 类型

  • http://schemas.google.com/g/2005#netmeeting

1.0 联系人类型的以下元素不再受支持:

gd:email 的更改

2.0 版中的 gd:email 中添加了新属性 @displayName

gd:organization 的更改

2.0 中引入了 gd:organization 的以下子元素:

  • gd:orgDepartment
  • gd:orgJobDescription
  • gd:orgSymbol
  • gd:where

gd:orgName 的更改

在 2.0 版本中,通过向元素添加 @yomi 属性增强了元素 gd:orgName

返回页首