常見問題

總覽

1. 什麼是 Google Data API？
2. 我有功能要求或錯誤報告。應該將代碼張貼在何處？
3. 如果對特定 API 有疑問，應如何提出？
4. 什麼是 JSON？
5. 我是否必須使用 XML？是否有其他資料格式可供使用？
6. 為什麼要使用 REST？
7. 你有任何常見問題的提示或簡短程式碼範例嗎？
8. Gmail 是否有資料 API？

驗證

9. 在 ClientLogin 中，各項 Data API 的服務名稱為何？
10. 使用者登出應用程式時，是否需要通知 API 伺服器？
11. ClientLogin 驗證權杖有到期日嗎？
12. 我有關於 Google 帳戶的一般問題。我該去哪裡？
13. 如何向 API 驗證？
14. AuthSub/OAuth 1 範圍參數應使用哪個值？
15. AuthSub 權杖是否有多種類型？權杖會過期嗎？
16. ClientLogin 與 AuthSub/OAuth 1 的主要差異為何？
17. 我可以在第三方網頁應用程式中使用 ClientLogin 驗證嗎？
18. 什麼是人機驗證 (CAPTCHA)？
19. 如何產生人機驗證問題？
20. 我應該在網路應用程式中使用 ClientLogin 嗎？
21. 使用 AuthSub/OAuth 1 時，如何找出使用者的使用者名稱？
22. 如何搭配 Google Data API 用戶端程式庫使用 OAuth 1？
23. 如何搭配 Google Data API 用戶端程式庫使用 AuthSub？
24. 如何搭配 Google Data API 用戶端程式庫使用 ClientLogin？

用戶端程式庫

25. Google 支援哪些程式設計語言的用戶端程式庫？
26. 如何回報 Google Data 用戶端程式庫的錯誤或提出功能要求？
27. 如何在用戶端程式庫中啟用偵錯選項？
28. 哪裡可以找到用戶端程式庫類別的參考文件？

疑難排解

29. 有哪些好用的 HTTP 偵錯工具？
30. 如何取得 Java 用戶端程式庫中的 HTTP 記錄資訊？
31. 如何在 .NET 用戶端程式庫中取得 HTTP 記錄資訊？
32. 如何從 Google 資料動態饋給啟用 gzip 編碼？
33. 使用 PHP 用戶端時，為什麼會看到「Unable to Connect to sslv2」錯誤？
34. 如何取得說明動態消息的 Atom 服務文件？

總覽

什麼是 Google Data API？

Google Data API 是以 Google Data 通訊協定為基礎的 API。Google Data 通訊協定是以 Atom 1.0 和 RSS 2.0 聯合發布格式為基礎，並採用 Atom 發布通訊協定 (APP)。

Google Data 通訊協定會以各種方式擴充這些標準，並使用標準內建的擴充機制。動態消息符合 Atom 或 RSS 資訊聚合格式。發布模型符合 Atom 發布通訊協定。

這個通訊協定也提供動態消息、查詢和結果的一般模型。您可以使用這項工具，將查詢和更新傳送至任何 Data API。

我有功能要求或錯誤報告。我該在哪裡發布貼文？

請參閱我們的問題追蹤工具。 找到所需功能要求，然後加上星號表示支持，並接收狀態更新。

如果對特定 API 有疑問，應該在哪裡提問？

如果您的問題未列於此處，或想進一步瞭解，請加入各項 Google Data API 的專屬討論群組：

• G Suite (請參閱 G Suite 系列中的個別 API)
• 基礎
• Blogger
• 日曆
• 程式碼搜尋
• 聯絡人
• Google 協作平台
• 試算表
• 文件 清單
• 聯合登入 / OpenID
• 金融
• 健康
• Picasa 網路相簿
• 網站管理員工具
• YouTube

什麼是 JSON？

JSON 是指 JavaScript 物件標記法。

JSON 是一種輕量資料交換格式，簡單易用，因此廣受網頁開發人員採用。易於讀取和寫入；您可以使用任何程式設計語言剖析 JSON，且其結構會直接對應至大多數程式設計語言使用的資料結構。

如要進一步瞭解如何搭配使用 JSON 與 Google Data API，請參閱這篇文章。

我一定要使用 XML 嗎？是否有其他資料格式？

Google Data API 的預設資料格式為 XML，以 Atom 動態饋給的形式呈現。不過，要求動態消息時，您可以使用 alt 查詢參數指定替代格式。

• alt=rss
  回應資料會格式化為 RSS 動態消息。
• alt=json 或 alt=json-in-script
  傳回 Atom 動態饋給 XML 結構的 JSON 表示法。JSON 的優點是更容易在 JavaScript 用戶端程式碼中「剖析」。目前只能以唯讀選項使用 JSON。不過，搭配 Blogger、Google 聯絡人或 Google 日曆服務使用 JavaScript 用戶端程式庫，即可讀取及寫入資料。

  進一步瞭解如何要求及使用 JSON 動態消息。

• alt=atom-in-script
  與 alt=json-in-script 類似，但傳回的結果是 Atom XML 字串，而非 JSON。
• alt=rss-in-script
  與 alt=atom-in-script 類似，但結果會以 RSS XML 字串而非 Atom 形式傳回。

如要進一步瞭解替代格式，請參閱 Google 資料參考指南。

你為什麼要使用 REST？

REST 簡單、輕巧、可擴充，且非常適合用於表示及公開資料。

針對常見問題，你有什麼提示或簡短的範例程式碼嗎？

請瀏覽 Google Data API 提示網誌，取得用戶端程式庫和發出原始要求的相關說明。

Gmail 是否有資料 API？

不行，但您可以搭配 AuthSub 或 OAuth 1 使用 Gmail 的 Atom 資訊動態饋給，要求取得使用者未讀郵件的唯讀存取權。範圍應設為 https://mail.google.com/mail/feed/atom/。查詢範例如下：

GET https://mail.google.com/mail/feed/atom/

如要管理郵件，Gmail 也支援 IMAP/POP。

---

驗證

在 Google Data API 說明文件中，「OAuth」是指 OAuth 1；如需 OAuth 2.0 詳細資料，請參閱個別 API 的說明文件。

各項 Data API 的 ClientLogin 服務名稱為何？

「服務名稱」是簡短的字串，ClientLogin 驗證系統會用來識別 Google 服務。

Google API	服務名稱
Google Analytics Data API	analytics
G Suite API (網域資訊與管理)	apps
Google Sites Data API	jotspot
Blogger Data API	blogger
Book Search Data API	print
Calendar Data API	cl
Google Code Search Data API	codesearch
Contacts Data API	cp
Content API for Shopping	structuredcontent
Documents List Data API	writely
Finance Data API	finance
Gmail Atom 動態消息	mail
健康資料 API	health weaver (H9 沙箱)
地圖資料 API	local
Picasa 網路相簿資料 API	lh2
Sidewiki Data API	annotateweb
Spreadsheets Data API	wise
網站管理員工具 API	sitemaps
YouTube Data API	youtube

如要進一步瞭解 ClientLogin 要求中使用的其他參數，請參閱 ClientLogin 說明文件。

使用者登出應用程式時，是否需要通知 API 伺服器？

不需要。使用者登出應用程式時，不必通知 Google Data API。不過，如果應用程式不再需要使用已核發的 AuthSub 權杖，就應撤銷權杖。

ClientLogin 驗證權杖有到期日嗎？

ClientLogin 權杖的效期為核發日期起 2 週，但這項限制因服務而異，效期可能較短。

我有關於 Google 帳戶的一般問題。我該去哪裡？

請前往 Google 帳戶說明中心。

如何向 API 驗證？

您的 HTTP 要求必須包含授權標頭，其中含有透過 ClientLogin、AuthSub 或 OAuth 1 取得的權杖。

AuthSub/OAuth 1 範圍參數應使用哪個值？

AuthSub 和 OAuth 1 需要

scope 參數，才能識別應用程式可存取的 Google 服務。如需 OAuth 2.0 詳細資料，請參閱特定 API 的說明文件。

Google API	ClientLogin 服務名稱
Google Analytics Data API	https://www.google.com/analytics/feeds/
Google Sites Data API	http(s)://sites.google.com/feeds/
Blogger Data API	http://www.blogger.com/feeds/
Book Search Data API	http://www.google.com/books/feeds/
Calendar Data API	http(s)://www.google.com/calendar/feeds/
Contacts Data API	http(s)://www.google.com/m8/feeds/
Content API for Shopping	https://www.googleapis.com/auth/structuredcontent
Documents List Data API	http(s)://docs.google.com/feeds/
Finance Data API	http://finance.google.com/finance/feeds/
Gmail Atom 動態消息	https://mail.google.com/mail/feed/atom/
健康資料 API	https://www.google.com/health/feeds/ https://www.google.com/h9/feeds/ (H9 沙箱)
Maps Data API	http://maps.google.com/maps/feeds/
Picasa 網路相簿資料 API	http://picasaweb.google.com/data/
Portable Contacts API	http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API	http://www.google.com/sidewiki/feeds/
Spreadsheets Data API	http(s)://spreadsheets.google.com/feeds/
網站管理員工具 API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

AuthSub 權杖是否有多種類型？權杖會過期嗎？

AuthSub 權杖有兩種。第一個是單次使用的權杖，會透過「token」查詢參數提供給您的網路應用程式。這組符記首次用於核發服務時會過期，或是在換取工作階段符記時過期。

除非透過使用者或 AuthSubRevokeToken API 呼叫明確撤銷權杖，否則工作階段權杖不會過期。只有在原始 AuthSubRequest 網址指定 session=1 做為查詢參數時，單次使用權杖才能換取工作階段權杖。

ClientLogin 和 AuthSub/OAuth 1 的主要差異為何？

AuthSub 專為網頁應用程式設計，這項功能可確保使用者憑證直接從使用者的網路瀏覽器安全地傳送至 Google 伺服器，而非透過第三方網站。

ClientLogin 適用於已安裝的電腦應用程式。要求應用程式代表使用者將使用者憑證傳輸給 Google。

請參閱 Google 帳戶驗證 API 的說明文件。

我可以在第三方網頁應用程式中使用 ClientLogin 驗證嗎？

在第三方網路應用程式中使用 ClientLogin 是可接受的做法，但強烈建議不要這麼做。最佳做法是網頁應用程式絕不應要求使用者提供登入憑證 (這可能會遭到窺探)。應用程式應改為在伺服器端儲存使用者憑證，並使用單一「服務帳戶」向 Google 進行驗證。

什麼是人機驗證？

人機驗證 (Captcha，亦即全自動公開化圖靈測驗人機辨識) 是一種挑戰-回應式測驗，用於判斷使用者是否為真人。這個字詞是卡內基美隆大學的註冊商標。詳情請參閱 Wikipedia。我們已在 ClientLogin 中導入 CAPTCHA。

如何產生 CAPTCHA 驗證問題？

系統會使用專屬演算法，判斷驗證期間是否需要進行 CAPTCHA 驗證。如果使用錯誤憑證重複嘗試驗證，系統通常會產生 CAPTCHA 驗證問題。

我應該在網頁應用程式中使用 ClientLogin 嗎？

否，ClientLogin 應由使用者自有硬體上安裝的應用程式使用。 在網路應用程式中使用 ClientLogin API 不安全，因此強烈建議不要使用。

使用 AuthSub/OAuth 1 時，如何找出使用者的使用者名稱？

由於您只會收到 Google 提供的權杖，用來授權存取使用者的動態消息，因此您可能不知道使用者的名稱。如果想使用的動態消息網址包含使用者名稱，這可能會造成問題。在這種情況下，您可以使用特殊使用者名稱 default，表示「我正在使用驗證權杖的使用者」。

如何搭配 Google Data API 用戶端程式庫使用 OAuth 1？

請參閱「Using OAuth 1 with the Google Data API Client Libraries」(搭配 Google Data API 用戶端程式庫使用 OAuth 1) 一文。

如何搭配 Google Data API 用戶端程式庫使用 AuthSub？

請參閱「Using AuthSub with the Google Data API Client Libraries」(搭配 Google Data API 用戶端程式庫使用 AuthSub) 一文。

如何搭配 Google Data API 用戶端程式庫使用 ClientLogin？

請參閱「Using ClientLogin with the Google Data API Client Libraries」(搭配 Google Data API 用戶端程式庫使用 ClientLogin) 一文。

---

用戶端程式庫

Google 支援哪些程式設計語言的用戶端程式庫？

Google 官方支援 Java、.NET、Python 和 Objective-C 用戶端程式庫。此外，我們的合作夥伴 Zend 也撰寫了 PHP 用戶端程式庫。您可以使用這些程式庫建構 Google Data 通訊協定要求、將要求傳送至服務，以及處理伺服器回應。此外，還有 JavaScript 用戶端程式庫，目前僅支援 Blogger、Google 日曆和 Google 聯絡人。

如果您使用 Java、.Net、Python 或 Objective-C 以外的語言編寫用戶端程式庫，並想與 Data API 開發人員社群分享，請在 Google Data API 討論群組中發布。歡迎與我們分享你的意見！

如何回報用戶端程式庫的錯誤或提出功能要求？

如要回報用戶端程式庫的錯誤或提出功能要求，請前往下列位置：

• Java
• JavaScript
• .NET
• PHP
• Python
• Objective-C

發布錯誤後，請在適當 API 的開發人員論壇中建立討論串。

如何在 Google Data API 用戶端程式庫中啟用偵錯選項？

如要瞭解如何使用部分用戶端程式庫啟用偵錯功能，請參閱下列文章：Debugging Google Data API Clients: Exploring Traffic from Within your Program

哪裡可以找到用戶端程式庫類別的參考文件？

用戶端程式庫	參考指南
Java	Javadoc
JavaScript	JSdoc
.NET	NDoc
PHP	phpDoc
Python	PyDoc

---

疑難排解

有哪些好用的 HTTP 偵錯工具？

下方列出多種工具，但您可能也想閱讀「On the Wire: Network Capture Tools for API Developers」一文，深入瞭解 WireShark 和 Fiddler 的範例。

Wireshark

Wireshark 是「網路通訊協定分析工具」，這項工具可擷取網路流量並分析內容。如果您無法直接存取 HTTP 要求和回應串流，這項功能就非常實用，可協助您偵錯程式庫中發生的流量。由於應用程式與驗證服務之間的通訊是透過 SSL 加密，因此無法使用 Wireshark 分析這類流量。Wireshark 也可用於分析使用 tcpdump 等工具擷取的流量。開發人員提供 Wireshark 的原始碼和 Windows 安裝程式。許多平台都提供第三方套件。

Fiddler

Fiddler 是「HTTP 偵錯 Proxy」，如果您可以設定程式碼或執行階段環境，透過 Proxy 伺服器傳輸 HTTP 流量，Fiddler 就會介於應用程式和 Google 資料服務之間，讓您檢查流量。Fiddler 2 支援 SSL。Fiddler 目前僅適用於 Windows。

cURL

cURL 是一種指令列工具，可執行 HTTP/HTTPS 要求。這項功能非常實用，可快速測試與服務的互動，不必先在用戶端中建構 HTTP 支援。

如何在 Java 用戶端程式庫中取得 HTTP 記錄資訊？

Java 用戶端程式庫會使用 java.util.logging 套件，啟用 HTTP 要求記錄。這樣一來，您就能啟用要求和回應的標頭記錄，以及狀態碼和要求網址。目前系統不會記錄完整的要求和回應串流。這些記錄使用的記錄器名稱為 com.google.gdata.client.http.HttpGDataRequest。

如果伺服器傳回錯誤代碼，系統會擲回例外狀況。例外狀況類別會從 com.google.gdata.util.ServiceException 繼承，並包含名為 getResponseBody() 的公開方法。詳情請參閱 Javadoc。

如何在 .NET 用戶端程式庫中取得 HTTP 記錄資訊？

如果啟用追蹤功能，.NET 程式庫會使用 System.Diagnostics 追蹤方法記錄執行路徑。此外，如果發生錯誤，系統會擲回 GDataRequestException。例外狀況包含 ResponseString，可讓您存取 HTTP 回應的內容。

如何從 Google 資料動態饋給啟用 gzip 編碼？

如要從 Google Data API 接收以 gzip 編碼的回應，您必須執行下列兩項操作：設定「Accept-Encoding」標頭，並修改使用者代理程式來加入「gzip」字串。正確格式的標頭範例如下：

User-Agent: my program (gzip)
Accept-Encoding: gzip

使用 PHP 用戶端時，為什麼會看到「Unable to Connect to sslv2」錯誤？

自 2009 年 7 月起，我們開始在伺服器上停用 SSLv2，以防範安全風險。很抱歉，在 2007 年 7 月前發布的 PHP 用戶端程式庫早期版本 (1.0.0 版和更早版本) 有錯誤，會強制連線使用 SSLv2。連線至已停用 SSLv2 的伺服器時，會發生下列錯誤：

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

如要修正這項錯誤，請升級至新版 PHP 用戶端程式庫，可從 http://framework.zend.com/download 下載。

如果無法升級至較新版本，請將下列程式碼新增至應用程式，即可修正這個問題，其中 $gdata 是現有的 Zend_Gdata 執行個體 (或適當的子類別)：

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));

如何取得說明動態消息的 Atom 服務文件？

您可以在要求中傳遞 alt=atom-service 參數，取得 Atom 服務文件。注意：只有 Google Data API 第 2 版會傳回符合 AtomPub 服務文件語法的服務文件。Google Data API 第 1 版仍會傳回服務文件，但會根據較早的 AtomPub 草案規格 (兩個版本之間有語法和命名空間變更)。