顯示前 100 個檔案 &Google 雲端硬碟中的資料夾

1. 使用 Google Workspace API

本程式碼研究室會介紹如何使用 Google Workspace (舊稱 G Suite) 的 HTTP 型 RESTful API。為簡潔起見，範例將以 Python 撰寫，但您也可以選擇使用自己偏好的開發語言。您將瞭解入門主題，例如如何使用開發人員控制台建立/管理專案、取得授權憑證，以及安裝 API 用戶端程式庫。完成這些準備工作後，您將使用 Google 雲端硬碟 API 編寫應用程式，顯示 Google 雲端硬碟中的前 100 個檔案和資料夾。

課程內容

• 使用 Google/Cloud 開發人員控制台建立專案
• 在應用程式中取得及使用 OAuth2 應用程式憑證
• 瞭解如何使用 Google API 用戶端程式庫
• 使用 Google 和 Google Workspace API 編寫應用程式
• 使用 Google Drive API 取得檔案和資料夾資訊

軟硬體需求

• 連上網際網路並使用網路瀏覽器
• Google 帳戶 (Google Workspace 帳戶可能需要管理員核准)
• 熟悉 Linux 和 Mac OS X 等符合 POSIX 規範的系統
• 可使用程式碼編輯器或 Shell 指令建立來源檔案。
• Python (2 或 3) 的基本技能，但您可以使用任何支援的語言
• Google 雲端硬碟中的部分檔案和/或資料夾

2. 問卷調查

您會如何使用這個程式碼研究室教學課程？

僅閱讀 閱讀並完成練習

您對 Google Workspace 開發人員工具和 API 的體驗滿意嗎？

新手 中級 熟練

3. 總覽

在本程式碼研究室中，您將瞭解如何：

1. 下載適用於 Python 的 Google API 用戶端程式庫
2. 在 Google/Cloud 開發人員控制台中建立新專案
3. 取得應用程式所需的憑證
4. 使用這些憑證存取 Google Drive API

如果您不想使用 Python，歡迎使用您喜愛的開發工具實作本程式碼研究室 (支援語言的用戶端程式庫請參閱這裡)，並將 Python 範例視為 (可執行的) 虛擬程式碼。

4. 確認 Python 環境

本程式碼研究室要求您使用 Python 語言 (不過 Google API 用戶端程式庫支援多種語言，因此您可以使用偏好的開發工具建構對等項目，並將 Python 視為虛擬程式碼)。具體來說，本程式碼研究室支援 Python 2 和 3，但我們建議盡快改用 3.x 版。

在你的地點還是我們的地點？

Google 提供雲端開發環境，方便使用者操作，但開發人員也可以使用自己的本機開發環境。如果自行設定，請按照這些指南操作，確保設定與 Cloud Shell 提供的內容一致 (詳情請見下文)。如要進一步瞭解 Python 支援，請參閱這篇文章。

Cloud Shell 是使用者可直接透過 Cloud 控制台使用的便利工具，不需要本機開發環境，因此本教學課程完全可以在雲端完成，只要使用網路瀏覽器即可。如果您要開發或打算繼續使用 GCP 產品和 API，Cloud Shell 特別實用。具體來說，Cloud Shell 已預先安裝這兩個版本的 Python，因此您不必擔心。

Cloud Shell 也已安裝 IPython，這是高階互動式 Python 解譯器，我們建議使用這個解譯器，尤其是數據資料學或機器學習社群的成員。如果是，IPython 是 Jupyter Notebooks 和 Colab (Google Research 代管的 Jupyter Notebooks) 的預設解譯器。

IPython 會優先使用 Python 3 解譯器，但如果沒有 3.x 版，就會改用 Python 2。您可以從 Cloud Shell 存取 IPython，也可以在本機開發環境中安裝。按下 ^D (Ctrl-d) 鍵結束，並接受優惠以結束。啟動 ipython 的輸出範例如下：

$ ipython
Python 3.7.3 (default, Mar 4 2020, 23:11:43)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

如果您不想使用 IPython，也可以使用標準的 Python 互動式解譯器 (Cloud Shell 或本機開發環境)，同樣可以透過 ^D 結束：

$ python
Python 2.7.13 (default, Sep 26 2018, 18:42:22)
[GCC 6.3.0 20170516] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 
$ python3
Python 3.7.3 (default, Mar 10 2020, 02:33:39)
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

終端機視窗輸出內容

• 終端機/指令視窗中顯示的輸出內容 (如上所示) 代表 POSIX 相容系統 (例如 Linux 或 Mac OS X，包括 Cloud Shell) 上的輸出內容。
• 除非是為了區分指令和輸出內容，否則大部分時間不會顯示殼層提示 ($)。
• 如果您使用 Windows 環境，請參閱這份指南。

本程式碼研究室也假設您已安裝 pip 安裝工具 (Python 套件管理員和依附元件解析器)。這個工具會與 2.7.9 以上或 3.4 以上版本一併安裝。如果您的 Python 版本較舊，請參閱這篇安裝指南。視權限而定，您可能需要 sudo 或超級使用者存取權，但一般來說並非如此。您也可以明確使用 pip2 或 pip3，針對特定 Python 版本執行 pip。

本程式碼研究室的其餘部分會假設您使用 Python 3，如果 Python 2 與 3.x 的差異很大，我們會提供 Python 2 的具體操作說明。

超級使用者存取權？

如上所述使用 pip 工具時，可能需要超級使用者存取權才能安裝套件。如果您使用的系統不允許您安裝套件 (例如學校電腦)，可能需要使用 virtualenv 虛擬環境工具，在主目錄中建立完整的 Python 環境，並取得安裝套件的完整存取權。

*建立及使用虛擬環境

本節為選用內容，只有必須使用虛擬環境完成本程式碼研究室的學員 (如上方警告側欄所述)，才需要閱讀本節。如果電腦上只有 Python 3，只要發出這個指令，即可建立名為 my_env 的 virtualenv (您也可以選擇其他名稱)：

virtualenv my_env

不過，如果電腦上同時有 Python 2 和 3，建議您安裝 Python 3 virtualenv，方法是使用 -p flag，如下所示：

virtualenv -p python3 my_env

「啟用」新建立的 virtualenv，如下所示：

source my_env/bin/activate

確認您位於環境中，方法是觀察殼層提示是否已加上環境名稱，例如：

(my_env) $ 

現在您應該可以 pip install 任何必要套件，在這個環境中執行程式碼等。另一個好處是，如果您完全搞砸了，或遇到 Python 安裝毀損等情況，可以清除整個環境，不會影響系統的其他部分。

注意：完成程式碼研究室後，如要退出虛擬環境，請輸入 deactivate 指令，返回作業系統殼層或 Cloud Shell。

Cloud Shell 和虛擬環境

使用 Cloud Shell 時，您不需要虛擬環境 (如上所述)。Cloud Shell 包含 Cloud SDK 的所有預設 Python 套件，但新的虛擬環境不會。如果您選擇在 Cloud Shell 中使用虛擬環境，則需要完成該安裝程序。

5. 安裝 Python 適用的 Google API 用戶端程式庫

本程式碼研究室需要使用 Python 適用的 Google API 用戶端程式庫，因此安裝程序很簡單，甚至可能完全不需要執行任何操作。

我們先前建議您考慮使用 Cloud Shell，您可以在雲端透過網路瀏覽器完成整個教學課程。使用 Cloud Shell 的另一個原因是，許多熱門開發工具和必要程式庫已預先安裝。

*安裝用戶端程式庫

(選用) 如果您使用 Cloud Shell 或已安裝用戶端程式庫的本機環境，可以略過這個步驟。只有在您在本機開發，且尚未安裝 (或不確定是否已安裝) 這些項目時，才需要執行這項操作。最簡單的方法是使用 pip (或 pip3) 進行安裝 (包括視需要更新 pip 本身)：

pip install -U pip google-api-python-client oauth2client

確認安裝

這項指令會安裝用戶端程式庫，以及該程式庫依附的任何套件。無論您是使用 Cloud Shell 或自己的環境，請匯入必要套件，確認沒有匯入錯誤 (也沒有輸出內容)，藉此驗證是否已安裝用戶端程式庫：

python3 -c "import googleapiclient, httplib2, oauth2client"

如果您改用 Python 2 (透過 Cloud Shell)，系統會發出警告，指出該版本已遭淘汰：

*******************************************************************************
Python 2 is deprecated. Upgrade to Python 3 as soon as possible.
See https://cloud.google.com/python/docs/python2-sunset

To suppress this warning, create an empty ~/.cloudshell/no-python-warning file.
The command will automatically proceed in seconds or on any key.
*******************************************************************************

順利執行該匯入「測試」指令 (沒有錯誤/輸出內容) 後，您就可以開始與 Google API 通訊！

注意：oauth2client 已淘汰

oauth2client 程式庫已於 2017 年淘汰，並改用較新的替代方案。不過，新版程式庫尚未支援使用者授權和使用者憑證儲存功能，而這兩項功能是本程式碼研究室的必要條件。這些功能推出後，我們會遷移這個程式碼研究室。目前 oauth2client 仍可正常運作 (即使在維護模式下也一樣)，並為使用者提供 OAuth2 權杖的自動化、安全執行緒儲存和存取功能，且與 2.x/3.x 相容，但較新的程式庫目前不支援這些功能。

摘要

由於這是入門程式碼研究室，我們假設您是 Google 和 Google Workspace API 的新手。如果您已具備建立專案和使用者授權「OAuth 用戶端 ID」的經驗，如果是，請建立或重複使用現有專案，建立或重複使用現有 OAuth 用戶端 ID，然後略過接下來兩個模組，直接前往「顯示雲端硬碟檔案和資料夾應用程式」，或直接跳至「進階開發人員控制台用法」，以較少的指引查看這些步驟。

6. 在 Cloud 控制台中指定專案

使用 Google API 的應用程式需要專案。這些項目是在 Google Cloud 開發人員控制台 (簡稱「開發人員控制台」) 中管理。在本程式碼研究室中，我們只會使用 Google 雲端硬碟 API，因此我們提供了一個神奇連結 (下方步驟 1)，可執行下列操作：

• 前往開發人員控制台
• 逐步說明如何建立新專案 (或選擇現有專案)，以及
• 自動啟用 Drive API

開始吧！

1. 前往 console.developers.google.com/start/api?id=drive，然後登入 Google 帳戶。
2. 如果您還沒有任何專案，系統會顯示這個畫面，請接受 Google API 服務條款：

接受條款後，系統會建立名為「我的專案」的新專案，並自動啟用 Drive API。3. 如果您已建立專案 (可能是在先前的程式碼研究室中建立)，則會看到這個畫面：按一下「建立專案」下拉式選單，然後選擇現有專案或建立新專案。 選擇專案 (新專案或現有專案) 後，系統會自動為您啟用 Drive API。4. 確認啟用雲端硬碟 API 的方式如下： 5. 按一下「前往憑證」，前往下一個步驟。

7. *授權 API 要求 (使用者授權)

如果您已建立使用者帳戶授權憑證，且熟悉相關程序，可以略過這個部分。這與服務帳戶授權不同，後者的技術不同，請繼續閱讀下文。

授權簡介 (以及一些驗證)

如要向 API 發出要求，應用程式必須具備適當的授權。驗證是類似的字詞，用來描述登入憑證。使用登入資訊和密碼登入 Google 帳戶時，您會驗證自己的身分。通過驗證後，下一步是判斷您 (更確切地說，是您的程式碼) 是否有權存取資料，例如 Cloud Storage 中的 Blob 檔案，或是 Google 雲端硬碟中的使用者個人檔案。

Google API 支援多種授權類型，但Google Workspace API 使用者最常使用使用者授權，因為本程式碼研究室中的範例應用程式會存取屬於使用者的資料。這些使用者必須授權您的應用程式存取他們的資料。也就是說，程式碼必須取得使用者帳戶的 OAuth2 憑證。

如要取得使用者授權的 OAuth2 憑證，請返回 API 管理工具，然後選取左側導覽列的「憑證」分頁：

進入該頁面後，您會看到所有憑證，並分為三個部分：

第一個是 API 金鑰，第二個是 OAuth 2.0 用戶端 ID，最後一個是 OAuth2 服務帳戶，我們使用的是中間那個。

授權類型：

1. API 金鑰代表 API 金鑰授權，用於存取公開資料，例如：搜尋 YouTube 影片、將句子傳送至 Cloud Natural Language API、存取 Google 地圖上的位置，或將圖片傳送至 Cloud Vision API。
2. OAuth 用戶端 ID 代表 OAuth2 使用者帳戶授權，適用於會存取使用者資料的應用程式，例如 Google 雲端硬碟檔案、將影片新增至使用者的播放清單，或將資料列新增至 Google 試算表。
3. 服務帳戶與使用者帳戶授權類似，唯一的差別在於資料是由其他應用程式或機器人使用者擁有，而非真人使用者。OAuth2 服務帳戶授權是存取 GCP API 的主要方式。

建立憑證

在「憑證」頁面中，按一下頂端的「+ 建立憑證」按鈕，然後在隨即顯示的對話方塊中選擇「OAuth 用戶端 ID：」。

在下一個畫面中，您可以執行 2 項操作：設定應用程式的授權「同意畫面」，以及選擇應用程式類型：

如果您尚未設定同意畫面，主控台會顯示警告，請立即設定。(如果已設定同意畫面，請略過後續步驟)。

OAuth 同意畫面

按一下「設定同意畫面」，然後選取「外部」應用程式 (如果您是 Google Workspace (舊稱「Google Workspace」) 客戶，請選取「內部」)：

請注意，在本練習中，您選擇哪個選項都沒關係，因為您不會發布程式碼研究室範例。大多數人會選取「外部」，然後前往較複雜的畫面，但您只需要完成頂端的「應用程式名稱」欄位：

目前您只需要應用程式名稱，因此請選擇反映您所進行程式碼研究室的名稱，然後按一下「儲存」。

建立 OAuth 用戶端 ID (使用者帳戶授權)

現在返回「憑證」分頁，建立 OAuth2 用戶端 ID。您可以在這裡建立各種 OAuth 用戶端 ID：

我們正在開發指令列工具，也就是「Other」(其他)，因此請選擇該選項，然後按一下「Create」(建立) 按鈕。選擇反映您要建立應用程式的用戶端 ID 名稱，或直接使用預設名稱 (通常是「其他用戶端 N」)。

儲存憑證

1. 系統會顯示含有新憑證的對話方塊，按一下「確定」即可關閉

2. 返回「憑證」頁面，向下捲動至「OAuth2 用戶端 ID」部分，找到新建立的用戶端 ID，然後點選最右下方的下載圖示 。
3. 系統會開啟對話方塊，將名為 client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json 的檔案儲存到「下載」資料夾。建議您將名稱縮短為較簡單的名稱 (例如 client_secret.json，這是範例應用程式使用的名稱)，然後儲存到您要在本程式碼研究室中建立範例應用程式的目錄/資料夾。

Cloud Shell 使用者：

如果使用 Cloud Shell，則必須在雲端安裝這個檔案... 2 個選項：

1. 在頂端列的殼層右側，找到「串連」或「雪人」選單 (3 個垂直小點)，然後選取「Upload File」(上傳檔案)，上傳剛下載的 JSON 檔案，並將其重新命名為 client_secret.json (如果尚未在本機執行這項操作)。

2. 在檔案系統中 cat client_secret.json，複製內容，然後在 Cloud Shell 中 cat > client_secret.json，貼上內容並按下 ^D (Ctrl-D) 鍵儲存。

將檔案移至您要建立範例應用程式的相同目錄/資料夾。

摘要

取得憑證後，您現在可以從應用程式存取 Drive API，但請注意，OAuth 用戶端 ID 的用途是讓使用者授予應用程式權限，以存取自己的資料。

NOTE：如要進一步瞭解如何手動 (不使用上述「精靈」) 建立專案、啟用 API 及取得憑證，請在本程式碼研究室結束後繼續學習。

8. 顯示雲端硬碟檔案和資料夾應用程式

無論是在本機開發環境或 Cloud Shell 中，請在 client_id.json 憑證檔案所在的目錄中，建立名為 drive_list.py 的新 Python 檔案，然後新增下列程式碼行：

from __future__ import print_function

from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools

SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
    creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))

files = DRIVE.files().list().execute().get('files', [])
for f in files:
    print(f['name'], f['mimeType'])

應用程式結構

這個應用程式分為三個主要部分：

1. Python 匯入作業，可帶入程式庫功能
2. 取得應用程式憑證
3. 擷取並顯示使用者 Google 雲端硬碟中的檔案和資料夾名稱及 MIME 類型

NOTE：本程式碼研究室結束後，您將可深入瞭解程式碼，並逐行查看說明，以便進一步學習。

執行應用程式

將這個檔案命名為 drive_list.py 等名稱。首次執行指令碼時，指令碼不會有權限存取使用者雲端硬碟 (您的雲端硬碟) 中的檔案。執行作業暫停時，輸出內容如下所示：

$ python3 ./drive_list.py
/usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory
 warnings.warn(_MISSING_FILE_MESSAGE.format(filename))

Your browser has been opened to visit:
  https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code

If your browser is on a different machine then exit and re-run this
application with the command-line parameter

 --noauth_local_webserver

從本機開發環境

瀏覽器視窗開啟並顯示 OAuth2 權限對話方塊時，指令列指令碼會暫停：

應用程式會在此要求使用者授予程式碼要求的權限 (透過 SCOPES 變數)。在本例中，這項權限是指從使用者的 Google 雲端硬碟查看檔案中繼資料的權限。可以。在程式碼中，這些權限範圍會顯示為 URI，但系統會在 OAuth2 流程對話方塊中，將其翻譯為地區設定指定的語言。使用者必須明確授權所要求的權限，否則程式碼的「執行流程」部分會擲回例外狀況，且指令碼不會繼續執行。

NOTE：部分使用者有多個瀏覽器，授權要求可能會在非慣用瀏覽器中彈出。如果是這樣，只要從不想使用的瀏覽器視窗複製完整網址，然後貼到想使用的瀏覽器網址列即可。

透過 Cloud Shell

如果您不小心在 Cloud Shell 中執行程式，系統不會彈出任何瀏覽器視窗，導致您無法繼續操作。發現底部的診斷訊息是傳送給你的，也就是這則訊息：

If your browser is on a different machine then exit and re-run this
application with the command-line parameter

 --noauth_local_webserver

以這種方式執行時，您會看到下列輸出內容：

$ python3 drive_list.py --noauth_local_webserver
/usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory
 warnings.warn(_MISSING_FILE_MESSAGE.format(filename))

Go to the following link in your browser:

  https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code

Enter verification code:

按照操作說明前往含有該網址的其他瀏覽器分頁，您會獲得與上述本機開發環境幾乎相同的體驗。主要差異在於最後，您會看到另一個畫面，其中顯示驗證碼，請在 Cloud Shell 中輸入：

剪下這段程式碼並貼到終端機視窗。

摘要

使用者點選「允許」和/或將驗證碼貼到提示中後，應用程式就會 (繼續) 執行，因此您應該會看到由雲端硬碟檔案/資料夾及其 MIME 類型組成的輸出內容。以下是其中一個測試帳戶的範例：

$ python3 ./drive_list.py
Travel expenses application/vnd.google-apps.spreadsheet
Gmail Add-ons codelab application/vnd.google-apps.script
Google Workspace Developer Intro application/vnd.google-apps.presentation
Baseball Sheets application/vnd.google-apps.folder
My Resume application/vnd.google-apps.document
  . . .

請注意，在後續執行作業時，系統不會再提示您授權 (因為授權程式庫已快取授權)，而是直接輸出結果。第一次在終端機中看到文件，是不是很令人興奮？我們認為是這樣！

9. 結語

現在，您已準備好進一步瞭解雲端硬碟 API 的功能，或探索其他 Google Workspace (Gmail、Google 文件、試算表、簡報、日曆) 和其他 Google API (地圖、Analytics、YouTube 等)。恭喜你完成本課程！

本程式碼研究室的程式碼也會放在 GitHub 存放區 (github.com/googlecodelabs/gsuite-apis-intro)，(我們會盡量讓本程式碼研究室與存放區保持同步)。準備好繼續了嗎？下方提供各種資源，可協助您深入瞭解本程式設計教學課程涵蓋的內容，或探索其他透過程式存取 Google 技術的方法。

如先前所述，如果您不是 Python 開發人員，歡迎以您偏好的開發語言重新完成這個程式碼研究室範例。如要取得支援語言的用戶端程式庫，請按這裡。

其他研究

您已具備 Drive API 的使用經驗，建議進行下列練習，進一步提升技能：

1. ZIP 檔案：編寫應用程式，將多個 ZIP 封存檔備份到雲端硬碟，並即時解壓縮，讓每個 ZIP 檔案名稱都成為這些檔案所屬的資料夾名稱。加分題：支援其他 ZIP 檔案內的遞迴 ZIP 封存檔案，以及其他資料夾內嵌的雲端硬碟資料夾。如果遇到困難，請參閱這個 Node.js 範例應用程式。
2. 相簿：撰寫相簿生成工具的開頭，將多張圖片上傳至 Google 雲端硬碟，並依時間戳記和地理位置整理到不同資料夾。加分題：尋找開放原始碼的圖像處理程式庫，並將每個資料夾中的所有相片縫合在一起，呈現你可能經歷的事件 (例如旅行、晚餐等)。
3. 探索 GCP：編寫可將 Google Workspace 和 Google Cloud Platform (GCP) 連結在一起的應用程式。編寫工具，將 Google 雲端硬碟中的圖片檔案備份到 Google Cloud Storage (GCS)，這是另一種「雲端檔案儲存」解決方案。您可能會覺得使用 GCS 比雲端硬碟更簡單，因為 GCS 具有進階的用戶端程式庫。
4. 分析及記錄：將解決方案擴展至步驟 3，方法是將備份的每張圖片傳遞至 Google Cloud Vision API，並取得 API 在這些圖片中看到的頂端 (3、5、10)「標籤」。針對每張圖片，在 Google 試算表中寫入一個資料列，其中包含 Cloud Vision 的分析結果，以及圖片在 GCS 中的備份位置。如果放棄，請參閱這個 Python 程式碼研究室。

10. 其他資源

說明文件

• Google 雲端硬碟 API 說明文件 (REST API 和 Android 原生 SDK/API)
• 其他 Google Workspace API 說明文件
• 其他 Google API 說明文件
• Google API 用戶端程式庫
• OAuth2 說明文件

相關和一般影片

• 建立新的 Google API 專案 ( 網誌文章和影片)
• 查看 Python 授權樣板程式碼 ( 影片)
• 列出 Google 雲端硬碟中的檔案 ( 影片、網誌文章)
• Google Drive API 影片庫
• Launchpad Online 影片系列 (前身為...)
• Google Workspace 開發人員節目系列影片

最新消息與更新

• Google Workspace 開發人員網誌
• Google Workspace 開發人員 Twitter (@GSuiteDevs)
• Google Workspace 開發人員每月電子報

其他程式碼研究室

入門

• [Apps Script] Google Apps Script 簡介

中級

• [Apps Script] CLASP Apps Script 指令列工具
• [Apps Script] Gmail 外掛程式
• [Apps Script] 文件外掛程式和 GCP Natural Language API
• [Apps Script] Hangouts Chat 機器人架構
• [REST API] 自訂報表工具 (Sheets API)
• [REST API] Github 授權 BigQuery 分析工具的自訂投影片產生器 (Slides+BigQuery API)

進階

• [REST API] 雲端圖片處理工作流程 (Drive、Cloud Storage、Cloud Vision、Sheets API)

參考應用程式

• Markdown 轉 Google 簡報轉換器 (Slides REST API)

11. *應用程式詳細說明

這個選用部分可在課程結束後做為自學內容，填補可能出現的任何缺口，或進行深入研究。

Python 匯入作業，可帶入程式庫功能

from __future__ import print_function

from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools

• 第一個 import 陳述式可讓這段程式碼在 Python 2 上執行，如果您只使用 Python 3，則可完全捨棄這個陳述式。
• 其中一項 Python 樣式指南是將標準程式庫和第三方模組匯入作業分開，這就是空白行的用途。
• 接下來的三個匯入項目會從 Google API 用戶端程式庫匯入必要的類別和函式，這些都是我們編寫這個應用程式時需要的項目。簡而言之，這些項目會執行下列動作：
• googleapiclient 著重於連線至 Google API
• httplib2 提供應用程式使用的 HTTP 用戶端
• oauth2client 有助於管理 OAuth2 憑證

授權及取得應用程式憑證

SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
    creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))

• 應用程式 SCOPES 是指應用程式會要求執行應用程式的使用者授予的權限。為確保使用者資料安全，應用程式必須獲得授權才能執行
• 建議您使用應用程式運作所需的最嚴格權限。為什麼？
• 安裝或執行應用程式時，如果應用程式要求大量權限，是不是很令人困擾？告訴您，現在您是另一方，要向使用者要求所有這些權限。使用限制較嚴格的範圍，可減少要求存取權，讓使用者更放心安裝您的應用程式。
• 大多數範圍看起來都像長網址，雲端硬碟中繼資料範圍也不例外。

SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'

• 應用程式必須有權杖才能與 Google 伺服器通訊。從 Google 傳回的有效權杖會儲存在權杖儲存檔案 storage.json 中。如果沒有儲存這些權杖，每次執行應用程式時，都必須重新授權。

store = file.Storage('storage.json')

• 這個應用程式會先檢查儲存空間中是否已有有效憑證 (請參閱 if 陳述式條件)。

creds = store.get()
if not creds or creds.invalid:

• 如果沒有憑證或憑證已過期，則必須從您下載的 client_id.json 檔案中，透過 OAuth 用戶端 ID 和密鑰，建立新的授權流程 [透過 oauth2client.client.flow_from_clientsecrets()]。

if not creds or creds.invalid:
    flow = client.flow_from_clientsecrets('client_id.json', SCOPES)

• 應用程式有流程後，必須執行流程，才能向使用者顯示上述 [透過 oauth2client.tools.run_flow()] 說明和圖示的 OAuth2 權限畫面。

    creds = tools.run_flow(flow, store)

• 使用者按一下「允許」，即表示同意應用程式存取 Google 雲端硬碟檔案中繼資料，而 Google 伺服器會傳回存取 API 的權杖。這些檔案會以 creds 形式傳回，並快取在 storage.json 檔案中。
• 此時，您的應用程式已具備有效憑證，可發出 API 呼叫。呼叫 googleapiclient.discovery.build() 會為您使用的 API 建立服務端點。
• 如要使用 build()，請傳遞所需的 API 名稱 ('drive') 和版本 (目前為 'v3')。
• 最後一個參數是 HTTP 用戶端，用於加密的 API 呼叫。

DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))

擷取並顯示前 100 個雲端硬碟檔案/資料夾和 MIME 類型

files = DRIVE.files().list().execute().get('files', [])
for f in files:
    print(f['name'], f['mimeType'])

• 下一行程式碼會呼叫 Drive API 的 files() 集合中的 list() 方法，以建構要求，並立即透過 execute() 呼叫該要求。系統會傳回 Python dict，我們要求提供 'files' 鍵，從使用者的 Google 雲端硬碟取得 100 個檔案和資料夾名稱 (如果檔案較少，則會取得較少的名稱)。
• 為什麼是 100？這是 DRIVE.files().list() 的預設值。如要變更這個數字 (例如只傳回 10 個檔案或 1000 個檔案)，請在要求中加入 pageSize 參數：DRIVE.files().list(pageSize=10)。如要瞭解更多選項，請參閱這份說明文件。
• 指令碼的最後一部分會逐一檢查每個檔案，並顯示檔案名稱和檔案 MIME 類型。

您已編寫第一個使用 Google REST API 的應用程式，恭喜！除了匯入和授權程式碼，這個指令碼實際上只有幾行程式碼 (如上所示)。大多數 Google API 的運作方式都類似，您只需要為每個要使用的 API 建立服務端點。

在應用程式中使用多個 Google API

可以，您當然可以在同一個應用程式中使用多個 API！以下是應用程式的 Python 程式碼片段，該應用程式會重複使用相同的 HTTP 用戶端，並建立服務端點來存取三項 Google API (沒錯，也使用 3 個不同的 SCOPES)：

SCOPES = (
    'https://www.googleapis.com/auth/drive',
    'https://www.googleapis.com/auth/spreadsheets.readonly',
    'https://www.googleapis.com/auth/presentations',
)

    . . .

HTTP   = creds.authorize(Http())
DRIVE  = discovery.build('drive',  'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)

我們認為這段程式碼可以做為應用程式的一部分，根據試算表資料 (Google 試算表 API) 產生多個投影片組 (Google 簡報 API)，並針對產生的每個投影片組使用複製的投影片範本 (Google 雲端硬碟 API)。雖然沒有這類應用程式，但您應該可以使用 Google Workspace 團隊建立的兩個現有範例做為建構區塊，建構類似的應用程式：

• 在投影片中取代文字和圖片 ( 網誌文章和影片) - 使用 Drive API 複製投影片範本，然後使用 Slides API 變更文字和圖片預留位置
• 根據試算表資料產生投影片 ( 網誌文章和影片)：從試算表讀取資料 (Sheets API)，並根據該資料建立投影片 (Slides API)

您的挑戰：建構該應用程式！

12. *進階開發人員控制台使用方式

在本選用章節中，我們將說明如何在開發人員控制台中建立專案、啟用 API 及取得憑證，而且不使用程式碼實驗室中的精靈。這項功能適合有一定程度的使用者，他們可以手動執行這項操作，或想瞭解如何執行這項操作。

在 Cloud 控制台中指定專案

使用 Google API 編寫應用程式時，您必須擁有專案。您可以重複使用現有專案，也可以建立新專案。這項操作會在 Cloud 控制台中進行。部分程式碼研究室提供魔法連結 (類似設定精靈)，可讓您快速開始，並略過許多必要步驟。但並非所有專案都適用，因此這些操作說明僅供一般參考。

只要使用 Google 憑證登入，並在控制台頂端看到專案下拉式選單，您就能在 Cloud 控制台的大部分畫面中建立專案。請注意，這裡的大部分螢幕截圖都是從 API 管理工具 (又稱 Developers Console) 擷取，只要按一下左側導覽列中的「API 管理工具」，或直接將瀏覽器指向 console.developers.google.com，即可輕鬆存取。

1. 如果您尚未建立任何專案，系統可能會將您帶往...
2. 「資訊主頁」頁面：
3. 「圖書館」頁面：
4. 或是完全空白的頁面：如果發生這種情況，請重新整理瀏覽器，系統會將你帶往「圖書館」頁面。
5. 無論是在「資訊主頁」或「圖書館」頁面，都請按一下頁面頂端的專案選取器：
6. 接著會顯示選取器對話方塊。按一下右側的「+」建立新專案：
7. 按一下「+」後，畫面上會顯示「新專案」頁面。所有個人帳戶預設可建立 12 個專案。建立第一個專案前，您必須先接受 Google API 服務條款：

完成上述步驟後，日後建立專案時，系統就不會再詢問電子郵件和服務條款問題：

5. 如果您過去曾建立至少一個專案，登入後系統會將您帶往上次處理的專案資訊主頁。然後依序選擇「選取專案」 >「+」，建立新專案。6. 建立新專案後，系統會將您帶回「資訊主頁」頁面：

您已成功建立專案，可以選擇要用於專案的 API，繼續進行後續步驟。

啟用 Google API

您必須先啟用 Google API，才能開始使用。以下範例說明如何啟用 Cloud Vision API。在本程式碼研究室中，您可能會使用一或多個 API，因此請按照類似步驟啟用這些 API，再開始使用。

透過 Cloud Shell

您可以使用 Cloud Shell 執行下列指令，啟用 API：

gcloud services enable vision.googleapis.com

注意：如果這項指令發生錯誤，請確認目前的專案 ID 與程式碼研究室專案 ID 相符。

使用下列指令找出 Cloud Shell 目前使用的專案 ID：

gcloud info | grep "project"

如果專案 ID 不正確，請使用下列指令來使用正確的專案 ID：

gcloud config set project <PROJECT_ID>

將 <PROJECT_ID> 替換為正確的專案 ID。

透過 Cloud 控制台

您也可以在 API 管理工具中啟用 Vision API。前往 Cloud 控制台的 API 管理工具，然後選取「程式庫」。

在搜尋列中輸入「vision」，然後選取顯示的 Vision API。輸入時畫面可能如下所示：

選取 Cloud Vision API，即可看到下方的對話方塊，然後按一下「啟用」按鈕：

費用

雖然許多 Google API 都能免費使用，但 GCP (產品和 API) 並非免費。啟用 Vision API 時 (如上所述)，系統可能會要求您提供有效的帳單帳戶。使用者應先參考 Vision API 的價格資訊，再啟用這項功能。請注意，部分 Google Cloud Platform (GCP) 產品提供「一律免費」方案，您必須超出用量才會產生費用。在本程式碼研究室中，每次呼叫 Vision API 都會計入免費方案，只要每月總用量不超過限制，就不會產生任何費用。

部分 Google API (例如 Google Workspace 的使用費用已納入月度訂閱方案，因此使用 Gmail、Google 雲端硬碟、日曆、文件、試算表和簡報 API 時，不會直接產生費用。不同 Google 產品的計費方式不同，因此請務必參閱 API 的說明文件，瞭解相關資訊。

摘要

在本程式碼研究室中，您只需要開啟 Google Drive API，因此請按照上述操作說明搜尋「Drive」。啟用後即可繼續操作。

授權 API 要求 (使用者授權)

授權簡介 (以及一些驗證)

如要向 API 發出要求，應用程式必須具備適當的授權。驗證是類似的字詞，用來描述登入憑證。使用登入資訊和密碼登入 Google 帳戶時，您會驗證自己的身分。通過驗證後，下一步是判斷您 (更確切地說，是您的程式碼) 是否有權存取資料，例如 Cloud Storage 中的 Blob 檔案，或是 Google 雲端硬碟中的使用者個人檔案。

Google API 支援多種授權類型，但Google Workspace API 使用者最常使用使用者授權，因為本程式碼研究室中的範例應用程式會存取屬於使用者的資料。這些使用者必須授權您的應用程式存取他們的資料。也就是說，程式碼必須取得使用者帳戶的 OAuth2 憑證。

如要取得使用者授權的 OAuth2 憑證，請返回 API 管理工具，然後選取左側導覽列的「憑證」分頁：

進入該頁面後，您會看到所有憑證，並分為三個部分：

第一個是 API 金鑰，第二個是 OAuth 2.0 用戶端 ID，最後一個是 OAuth2 服務帳戶，我們使用的是中間那個。

授權類型：

1. API 金鑰代表 API 金鑰授權，用於存取公開資料，例如：搜尋 YouTube 影片、將句子傳送至 Cloud Natural Language API、存取 Google 地圖上的位置，或將圖片傳送至 Cloud Vision API。
2. OAuth 用戶端 ID 代表 OAuth2 使用者帳戶授權，適用於會存取使用者資料的應用程式，例如 Google 雲端硬碟檔案、將影片新增至使用者的播放清單，或將資料列新增至 Google 試算表。
3. 服務帳戶與使用者帳戶授權類似，唯一的差別在於資料是由其他應用程式或機器人使用者擁有，而非真人使用者。OAuth2 服務帳戶授權是存取 GCP API 的主要方式。

建立憑證

在「憑證」頁面中，按一下頂端的「+ 建立憑證」按鈕，然後在隨即顯示的對話方塊中選擇「OAuth 用戶端 ID：」。

在下一個畫面中，您可以執行 2 項操作：設定應用程式的授權「同意畫面」，以及選擇應用程式類型：

如果您尚未設定同意畫面，主控台會顯示警告，請立即設定。(如果已設定同意畫面，請略過後續步驟)。

OAuth 同意畫面

按一下「設定同意畫面」，然後選取「外部」應用程式 (如果您是 Google Workspace 客戶，請選取「內部」)：

請注意，在本練習中，您選擇哪個選項都沒關係，因為您不會發布程式碼研究室範例。大多數人會選取「外部」，然後前往較複雜的畫面，但您只需要完成頂端的「應用程式名稱」欄位：

目前您只需要應用程式名稱，因此請選擇反映您所進行程式碼研究室的名稱，然後按一下「儲存」。

建立 OAuth 用戶端 ID (使用者帳戶授權)

現在返回「憑證」分頁，建立 OAuth2 用戶端 ID。您可以在這裡建立各種 OAuth 用戶端 ID：

我們正在開發指令列工具，也就是「Other」(其他)，因此請選擇該選項，然後按一下「Create」(建立) 按鈕。選擇反映您要建立應用程式的用戶端 ID 名稱，或直接使用預設名稱 (通常是「其他用戶端 N」)。

儲存憑證

1. 系統會顯示含有新憑證的對話方塊，按一下「確定」即可關閉

2. 返回「憑證」頁面，向下捲動至「OAuth2 用戶端 ID」部分，找到新建立的用戶端 ID，然後點選最右下方的下載圖示 。
3. 系統會開啟對話方塊，將名為 client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json 的檔案儲存到「下載」資料夾。建議您將名稱縮短為較簡單的名稱 (例如 client_secret.json，這是範例應用程式使用的名稱)，然後儲存到您要在本程式碼研究室中建立範例應用程式的目錄/資料夾。

Cloud Shell 使用者：

如果使用 Cloud Shell，則必須在雲端安裝這個檔案... 2 個選項：

1. 在頂端列的殼層右側，找到「串連」或「雪人」選單 (3 個垂直小點)，然後選取「Upload File」(上傳檔案)，上傳剛下載的 JSON 檔案，並將其重新命名為 client_secret.json (如果尚未在本機執行這項操作)。

2. 在檔案系統中 cat client_secret.json，複製內容，然後在 Cloud Shell 中 cat > client_secret.json，貼上內容並按下 ^D (Ctrl-D) 鍵儲存。

將檔案移至您要建立範例應用程式的相同目錄/資料夾。