常見問題

總覽

1. 什麼是 Google Data API？
2. 我有功能要求或錯誤報告。我要在哪裡張貼文章？
3. 要在哪裡提出有關特定 API 的問題？
4. 什麼是 JSON？
5. 我是否需要使用 XML？是否有其他可用的資料格式？
6. 您使用 REST 的理由
7. 您是否有常見問題的秘訣或簡短程式碼範例？
8. Gmail 有 Data API 嗎？

驗證

9. 在 DataLogin 中，每個 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. 如何產生人機驗證 (Captcha) 驗證問題？
20. 我應該在網路應用程式中使用 ClientLogin 嗎？
21. 如何使用 AuthSub/OAuth 1 找出使用者的使用者名稱？
22. 如何將 OAuth 1 與 Google Data API 用戶端程式庫搭配使用？
23. 如何將 AuthSub 與 Google Data API 用戶端程式庫搭配使用？
24. 如何將 ClientLogin 與 Google Data API 用戶端程式庫搭配使用？

用戶端程式庫

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

疑難排解

29. 有哪些良好的 HTTP 偵錯工具？
30. 如何在 Java 用戶端程式庫中取得 HTTP 記錄資訊？
31. 如何在 .NET 用戶端程式庫中取得 HTTP 記錄資訊？
32. 如何在 Google 資料動態饋給中啟用 gzip 編碼？
33. 使用 PHP 用戶端時，為什麼出現「無法連線到 sslv2」的錯誤？
34. 如何取得描述動態饋給的 Atom 服務文件？

---

總覽

什麼是 Google Data API？

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

Google Data 通訊協定運用標準內建的擴充功能機制，以各種方式擴展這些標準。動態饋給符合 Atom 或 RSS 聯合發布格式。發布模型符合 Atom 發布協定。

通訊協定也會為動態饋給、查詢和結果提供一般模型。可用來傳送查詢和更新至任何 Data API。

我有功能要求或錯誤報告。我要在哪裡張貼文章？

請參閱我們的Issue Tracker。尋找您的功能要求並加上星號，即可新增支援服務並加入處理進度。

要在哪裡提出有關特定 API 的問題？

如果這裡未列出您的問題，或您希望進一步釐清，每個 Google Data API 都有專屬的討論群組：

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

什麼是 JSON？

JSON 是指 JavaScript 物件標記法。

JSON 是一種輕量的資料交互格式，這種格式很容易讓網頁程式開發人員廣泛使用。可輕鬆讀取和寫入；您可以使用任何程式設計語言進行剖析，其結構會直接對應至大部分程式設計語言中使用的資料結構。

進一步瞭解如何搭配 Google Data API 使用 JSON。

我是否需要使用 XML？是否有其他可用的資料格式？

Google Data API 的預設資料格式為 XML，格式為 Atom 資訊提供。但在要求動態饋給時，您可以使用 alt 查詢參數指定替代格式。

• alt=rss
  回應資料的格式是 RSS 動態消息。
• alt=json 或 alt=json-in-script
  會傳回 Atom 資訊提供 XML 結構的 JSON 表示法。JSON 的額外優點，就是更容易在 JavaScript 用戶端程式碼中進行「剖析」。目前，JSON 只能做為唯讀選項使用。不過，如果您同時使用 JavaScript 用戶端程式庫與 Blogger、聯絡人或日曆服務，即可讀取及寫入資料。

  進一步瞭解要求及使用 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 提示網誌，取得 Google 用戶端程式庫的協助，以及提出原始要求。

Gmail 有 Data API 嗎？

否，但是您可以透過 Gmail 的 Atom 資訊提供 和 AuthSub 或 OAuth 1，要求存取使用者未讀取郵件的唯讀存取權。範圍應設為 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 的說明文件。

在 ClientLogin 中，各個 Data API 的服務名稱為何？

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

Google API	服務名稱
Google Analytics (分析) 資料 API	analytics
G Suite API (網域資訊與管理)	apps
Google 協作平台資料 API	jotspot
Blogger 資料 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
文件清單資料 API	writely
金融資料 API	finance
Gmail Atom 資訊提供	mail
健康資料 API	health weaver (H9 沙箱)
Maps Data API	local
Picasa Web 網路相簿資料 API	lh2
Sidewiki Data API	annotateweb
試算表資料 API	wise
網站管理員工具 API	sitemaps
YouTube Data API	youtube

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

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

否，當使用者登出應用程式時，並不需要通知 Google Data API。不過，如果您的應用程式不再需要使用核發的 AuthSub 憑證，則應撤銷憑證。

ClientLogin 驗證權杖是否設有到期日？

ClientLogin 權杖可在核發日期算起 2 週，但其限制因服務而異，並且可能較短。

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

請造訪 Google 帳戶說明中心。

如何向 API 進行驗證？

HTTP 要求中必須包含 Authorization 標頭，其中包含使用 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 協作平台資料 API	http(s)://sites.google.com/feeds/
Blogger 資料 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
文件清單資料 API	http(s)://docs.google.com/feeds/
金融資料 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 Web 網路相簿資料 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/
試算表資料 API	http(s)://spreadsheets.google.com/feeds/
網站管理員工具 API	http://www.google.com/webmasters/tools/feeds/
YouTube Data API	http://gdata.youtube.com

驗證子類別是否具有不同類型？符記是否過期？

驗證子類別有兩種。第一種憑證是透過「token」查詢參數提供給您的單一使用權杖，這組憑證首次針對核發憑證的服務使用，或用於交換工作階段符記時，就會過期。

除非使用者或 AuthSubRevokeToken API 呼叫已明確撤銷憑證，否則工作階段符記不會過期。原始的 AuthSubRequest 網址將 session=1 指定為查詢參數時，只能將單一使用權杖交換成工作階段符記。

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

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

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

請參閱 Google Account Authentication API 的說明文件。

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

您可以在第三方網路應用程式中使用 ClientLogin，但強烈建議不要這麼做。最佳做法是，網頁應用程式一律不得要求使用者提供登入憑證 (這可能容易遭到假冒)。應用程式應將伺服器端憑證儲存在伺服器端，並且具有單一「服務帳戶」，永遠用於 Google 驗證。

什麼是人機驗證 (Captcha)？

人機驗證 (Captcha) 是完全自動化的虛擬化實測測試，可讓電腦與人類進行區隔，這是一種驗證/回應測試，用來判斷使用者是否為真人。這個字詞是卡內基梅隆大學 (Carnegie Mellon University) 的商標。詳情請參閱維基百科。我們已在 ClientLogin 中導入人機驗證 (Captcha)。

如何產生人機驗證 (Captcha) 驗證問題？

系統會使用專屬演算法來判斷驗證期間是否需要人機驗證 (Captcha) 驗證。重複執行錯誤的憑證驗證通常會導致人機驗證 (Captcha) 驗證問題。

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

不可以，使用者登入的硬體應使用 ClientLogin。 在網路應用程式中使用 ClientLogin API 並不安全，因此強烈建議使用。

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

由於你獲得一個用來存取使用者動態饋給的 Google 權杖，因此你不知道他們的使用者名稱。如果你使用的動態消息網址包含使用者名稱，就可能會造成問題。在這種情況下，您可以使用特殊使用者名稱 default 來表示「我使用的驗證憑證使用者」。

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

請參閱「搭配 Google Data API 用戶端程式庫使用 OAuth 1」一文。

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

請參閱「搭配 Google Data API 用戶端程式庫使用 AuthSub」一文。

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

請參閱「搭配 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
• 目標 -

發布錯誤後，請在開發人員論壇中為適當的 API 建立執行緒。

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

請參閱下列文章，瞭解如何針對部分用戶端程式庫啟用偵錯功能：偵錯 Google Data API 用戶端：在程式中探索流量

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

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

---

疑難排解

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

下方列出的工具有很多種，但建議您也參閱「Wi-Fi: Network Capture Tools for API Developers」一文，該文章詳細說明瞭 WireShark 和 Fiddler 的深入範例。

Wireshark

Wireshark 是「網路通訊協定分析工具」，能夠擷取網路流量及分析內容。針對無法直接存取 HTTP 要求和回應串流的程式庫，當流量出現流量時，偵錯功能非常有用。您無法使用 Wireshark 分析應用程式與驗證服務之間的流量，因為通訊是透過 SSL 加密。此外，Wireshark 也可用來分析使用 tcpdump 等工具擷取的流量。開發人員可以提供 Wireshark 做為原始碼和 Windows 安裝程式。第三方套件適用於許多平台。

漁夫

Fiddler 是「HTTP 偵錯 Proxy」。如果您可以設定程式碼或執行階段環境，以便使用 HTTP 伺服器處理 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-Unicode」標頭，並將使用者代理程式修改為包含「gzip」字串。格式正確的標頭範例：

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

使用 PHP 用戶端時，為何出現「無法連線到 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 服務文件。注意：只有第 2 版 Google Data API 會傳回符合 AtomPub 服務文件語法的服務文件。第 1 版 Google Data API 仍會傳回服務文件，不過該文件是以先前的 AtomPub 草稿規格 (兩個版本之間有語法及命名空間變更) 為根據。