常見元素:「種類」

警告:本頁面說明 Google 的舊版 API (即 Google Data API);該 API 只與 Google Data API 目錄中列出的 API 相關,其中許多 API 已由新版 API 取代。如需特定新的 API 的相關資訊,請參閱新 API 的說明文件。如要瞭解如何使用新版 API 授權要求,請參閱 Google 帳戶驗證與授權

簡介

使用 Google Data API 的服務,往往能為一組特定項目提供一致的資訊。

舉例來說,各種 Google Data API (或稱「GData」) 服務可能會為個人或機構提供聯絡資訊,讓所有這類服務都使用同一組聯絡資訊元素是很合理的做法。

構成聯絡人的元素集合就稱為「種類」。「聯絡人」種類中的某些元素是一般的 Atom 或 RSS 元素,而其他元素則是由 Google 於名為「Google Data 命名空間」的命名空間中定義。按照慣例,Google 資料命名空間通常會以 gd: 別名,在 XML 程式碼中使用,例如,包含電話或傳真號碼的元素是 <gd:phoneNumber>。Google Data 命名空間的結構定義網址是 http://schemas.google.com/g/2005。

Google 也定義了其他種類:活動 (由一個代表標準日曆活動的標準化元素集合) 和「訊息」(代表電子郵件、討論群組訊息或其他訊息的元素集合)。

Google 資料命名空間的部分元素會用於各種類型。例如,<gd:who> 元素會將使用者 (如 <gd:who> 中所述) 與包含 <gd:who> 元素的項目建立關聯。這個事件可在活動種類中指定主辦人、參與者等等。且在「郵件」種類中使用,用於指定寄件者與收件者。

如果 Google Data API 資訊提供中的項目使用指定種類,該元素會包含 <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> 並未用於 Contact 種類,而且 <atom:author> 是項目中必要的元素 (除非已在上層動態饋給中指定該元素),但對於「聯絡人」種類並沒有什麼意義。

建立種類

要建立特定類型的項目可能並不容易,特別是某些種類的元素包含其他種類。

建議您使用我們提供的用戶端程式庫,而不要手動建立種類。用戶端程式庫會提供許多方法來新增和變更資料項目的方法;詳情請參閱用戶端程式庫說明文件。

擴充性

本文件中的資訊並未涵蓋所有可能的屬性種類和屬性值。服務可能會擴充種類,因此特定服務可以使用本文件未包含的屬性和值。

字體排放慣例

在本文件的表格中,我們針對必要及選用元素採用下列慣例:

元素名稱 必要元素
<元素名稱>? 選用元素
<元素名稱>* 選用元素,允許多個執行個體

元素和屬性會以標準 XPath 標記法呈現。

聯絡種類

代表聯絡人:一個人、一個場地 (例如俱樂部或餐廳),或是機構。

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

注意:如果您在 Contacts API 中使用 Contact 種類,也請注意 API 版本 3.0 後,Contact API 才會使用 Contact Kind 2.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 使用者或其他實體相關聯的設定檔。「個人資料」種類與 Contact 種類具備許多結構。但在某些方面有所不同:例如,不能包含擴充屬性或標示為已刪除。

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

「設定檔 API」3.0 版導入了設定檔類型。

屬性

屬性 說明
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 留言資訊提供。
gd:eventStatus 可擴充的列舉項目如下所述。
gd:extendedProperty* 擴充屬性。
gd:originalEvent 週期性活動的原始事件 ID。
gd:recurrence 重複規則。
gd:transparency 可擴充的列舉項目如下,對應於 RFC 2445 中定義的 TRANSP 屬性。
gd:visibility 可擴充的列舉項目如下所述。
gd:when* 事件時間。startTimeendTime 屬性都必須設定,不過對於全天活動而言,這些屬性只是日期,不含時間。
gd:when/gd:reminder* 活動提醒。
gd:where* 活動地點或附近必需品,例如停車場。如果動態饋給層級指定了 <gd:where> 元素,但項目層級沒有 <gd:where> 元素,則這些項目將沿用動態饋給層級的 <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 Data 命名空間元素參考資料

本文件的其餘部分,則包含 種類使用的 元素的參考資料。

列舉

部分擴充功能元素需要指定其值來自列舉的集合。這類屬性的一般形式如下:

<gd:propertyName value="propertyValue">

如果屬性值來自 Google 資料命名空間,則採用 http://schemas.google.com/g/2005#{Kind}.{value} 的格式。例如:http://schemas.google.com/g/2005#event.tentative。如果值空間可延伸,其值也可能是 URI 格式。擴充值 URI 的建議格式為 {結構定義 URI}#{value}。例如:http://www.example.com/attendeeStatus#AudioConference

gEnumConstruct =
   attribute value { text },
   anyAttribute*

gdCommonProperties

適用於所有 Google 類型的常見屬性。請注意,結構定義中存在 anyAttributeanyElement 時,所有使用通用屬性的 Google Data 命名空間元素都能進一步在所有命名空間中加以擴充。具體來說,將任何 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

包含封閉項目 (例如日曆活動) 的評論資訊提供。

屬性

屬性 類型 說明
@rel xs:string 包含的留言類型。目前區分一般評論和評論。
gd:feedLink feedLink 留言資訊提供。這個動態饋給應實作 Message 種類。

rel 值

說明
http://schemas.google.com/g/2005#regular 或未指定 一般使用者留言 (來自使用者)。
http://schemas.google.com/g/2005#reviews 專業評論:

範例

留言資訊提供:

<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>

評論資訊提供:

<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:deleted

標記元素存在時,表示包含的項目會遭到刪除。

屬性

無。

結構定義

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> 可能包含來自聯絡人資訊提供的巢狀項目。

屬性

屬性 類型 說明
@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 元素儲存為內嵌項目,或儲存在其他動態饋給中並建立連結。提醒您,部分服務可能不支援部分選項。

範例

<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 時,動態饋給可選擇性地將任何有效的 XML 嵌入 gd:extendedProperty 元素中 (與 value 屬性互斥)。

屬性

屬性 類型 說明
@name xs:string 指定以 URI 表示的屬性名稱。擴充屬性 URI 通常會遵循 {schema}#{local-name} 慣例。
@value xs:string 屬性值。
@realm xs:string 部分 API 會使用這個欄位來指定擴充屬性適用的位置。

範例

日曆活動的外部 ID:

<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

代表邏輯巢狀資訊提供。例如,日曆資訊提供可以有一個巢狀資訊提供,代表項目的所有評論。

屬性

屬性 類型 說明
@countHint xs:unsignedInt 代表資訊提供中的項目數量。視導入方式而定,可能不是精確的計數。
@href xs:string 指定資訊提供 URI。如果內嵌的動態消息未嵌入,則系統可能不會略過這項屬性。
@readOnly xs:boolean 指定內含的動態饋給是否處於唯讀狀態。
@rel xs:string 指定連結關係;允許服務為單一實體提供多種資訊提供連結。具有相同的語意和允許的值,與 <atom:link> 元素的 rel 屬性相同。
atom:feed atomFeed 動態饋給的內容。

限制

  • @href<atom:feed> 必須同時存在,或兩者皆有。
  • 如果沒有 atom:feed,用戶端可以從 @href 的 URI 中擷取內容。如果存在的話,內容必須與擷取動態饋給時從 @href 擷取的內容相同。
  • 當 PUT 或 POST 包含 <gd:feedLink> 且指定了 @href 屬性時,系統會使用屬性值來建立連結;如果 <atom:feed> 元素也存在,系統會忽略該值。如果未指定 @href 屬性,系統會將 <atom: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 項目內內嵌的資訊提供:

<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 用於為這個位置命名的簡單字串值。可讓 UI 顯示「目前位置」等標籤。
@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 網路。這個值可以是標準值 (如下方所示) 或 URI 來識別專屬 IM 網路。
@primary xs:boolean 聯絡人種類出現多個 IM 擴充功能時,請指定哪一個類型的主要電話號碼。最多只能有一個 IM 做為主要 IM。預設值為 "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 即時 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 的 IM 位址:

<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:givenName

指定使用者的姓名,例如:「大明」

屬性

屬性 類型 說明
@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 前綴前置字元,例如「Mrs」或「Mrs」
gd:nameSuffix nameSuffix 後置字串,例如「san」或「III」。
gd:fullName fullName 非結構化的名稱。

範例

肯塔基州溫斯頓·萊昂德·史賓塞爾‧切爾切爾爵士的結構化形象

<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:organizations

機構,通常與聯絡人相關聯。

屬性

屬性 類型 說明
@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 原始事件的事件資訊提供網址。

範例

指定原始事件:

<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 可明確識別一組數字,並讓 UI 顯示適當的標籤,例如「行動裝置」、「住家」、「公司」等。不過,如果一人使用 (例如) 多支手機,就可以利用這個屬性來區分它們。
@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 部分。)最後一個是 VGMT 元件,提供上述屬性中提及的任何時區 ID 的詳細時區規則。

Google 日曆等 Google 服務通常不會產生週期性活動的 EXRULE 和 EXDATE 屬性,而是產生 <gd:recurrenceException> 元素。不過,Google 服務可能仍含 EXRULE 和/或 EXDATE 屬性。舉例來說,使用者可以將活動和例外狀況匯入 Google 日曆;如果匯入的事件包含 EXRULE 或 EXDATE 屬性,則 Google 日曆傳送 <gd:recurrence> 元素時會提供這些屬性。

請注意,使用 <gd:recurrenceException> 代表您僅不確定檢查 <gd:recurrence> 元素是否有重複說明。為確保您能找到所有例外狀況,請在動態饋給中尋找 <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 點有會議,如果您在本週四的會議中更改出席狀況清單 (但不安排定期會議),那麼就會成為例外。如果你變更本週會議的會議時間 (但不包括定期會議),會議就會變成特殊參與者。

無論例外狀況是否具有特殊性,如果您執行的是刪除例外狀況的執行個體,則系統會刪除例外狀況。請注意,變更週期性活動的日期或時間會刪除所有活動,並建立新的活動。

舉例來說,假設您在下週四次開會後,將週期性會議安排在週一、週三和週五,這項變更會刪除星期二/週四會議中所有週期性的活動,包括特別會議。

如果刪除週期性活動的特定執行個體,該執行個體會顯示為 <gd:recurrenceException>,其中包含其 <gd:entryLink><gd:eventStatus> 設為 "http://schemas.google.com/g/2005#event.canceled"。(如要進一步瞭解已取消的活動,請參閱 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。部分服務會提供獨立 ID,用來建構後續的要求。確切用量會因服務而異。

範例

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

結構定義

start = resourceId

resourceId =
   element gd:resourceId { xs:string }

gd:結構化郵遞地址

郵寄地址分為不同部分。儲存地址時,可以採獨立語言代碼格式。系統可解讀這些欄位,並用來產生格式化的語言代碼地區地址。以下元素包含地址的某些部分:agent, House name, Street, P.O.box, 鄰近, City, subregion, region, 郵遞區號, countrysubregion 元素不用於郵寄地址,僅供延伸使用的地址使用。為了以非結構化格式格式化地址欄位儲存郵政地址,

屬性

屬性 類型 說明
@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 可蓋過 P.O. 實際盒子、抽屜、鎖包等。這通常是與街道互斥的情況。
gd:neighborhood neighborhood 當某個城市包含多條名稱相同的街道,或用於指定某個城市的郵遞經過較大的郵政城鎮時,此地址可用於區分街道地址。在中國,可以是縣市或小城市。
gd:city city 可以是城市、村落、城鎮、自治市鎮等。這裡是郵鎮,不一定是居住地或營業場所。
gd:subregion subregion 處理非美國郵遞地址的行政區域,例如美國或英國郡/縣。子區域不適用於寄送地址。
gd:region region 州、省、縣 (位於愛爾蘭)、土地 (德國)、外籍 (法國) 等。
gd:postcode postcode 郵遞區號。通常涵蓋整個國家/地區,但有時只適用於特定城市 (例如在「Dublin 2, Ireland」地址輸入「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, USA
<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>

私人位址:

杜莎夫人 (Dadame Duval)
21,路易巴斯爾 (Rue Youur)
14390 CABOURG
法國

結構定義

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:structuredPostAddress」。
  • 您只能指定一個結構化地址做為主要地址。
  • 非結構化的郵寄地址必須與結構化資料一致。

gd:when

代表一段時間或瞬間。

屬性

屬性 類型 說明
@endTime xs:dateTimexs:date 說明活動的結束時間。如未指定時區,系統會採用觀測器的當地時區。
@startTime xs:dateTimexs:date 說明活動的開始時間或 0-00 秒的事件。如未指定時區,系統會採用觀測器的當地時區。
@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"/>

為期 2 天的活動 (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"/>

持續時間為 0 的事件:

<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:who

與內含實體相關聯的人。關聯的類型取決於 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 種類。在許多情況下,此項目可能來自聯絡人資訊提供。

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 版中,元素 gd:orgName 新增了 @yomi 屬性以強化此元素。

返回頁首