從 Google Cloud 專案呼叫 API

1. 事前準備

本程式碼研究室說明如何建立 Google Cloud 專案，然後從該專案呼叫 Google Cloud API。

必要條件

  • 可瀏覽 Google Cloud 控制台。

課程內容

  • 如何建立 Google Cloud 專案
  • 如何設定帳單帳戶。
  • 如何設定 Cloud Shell。
  • 如何啟用 API。
  • 如何使用 API 金鑰授權 API。
  • 如何透過服務帳戶授權 API。

軟硬體需求

2. 做好準備

本節說明如何建立 Google Cloud 專案、設定帳單帳戶及設定 Cloud Shell。

建立 Google Cloud 專案並設定帳單帳戶

  1. 登入 Cloud 控制台，然後選取或建立專案。

Google Cloud

新增專案窗格

「New Project」窗格顯示「Project name」、「Organization」和「Location」欄位。

記住在「專案名稱」欄位下方的專案 ID。ID 是所有 Google Cloud 專案的專屬名稱 (已經有人使用這個名稱)，在本程式碼研究室的後續部分稱為 PROJECT_ID。

  1. 接下來，請在 Cloud 控制台中啟用計費功能，以便使用 Google Cloud 資源。

雖然本程式碼研究室不會耗用大量資源，但請按照「清除」一節中的操作說明，關閉資源並避免在本程式碼研究室以外的費用方面產生費用。請注意，Google Cloud 的新使用者符合免費試用$300 美元的資格。

設定 Cloud Shell

在本程式碼研究室中，您將使用 Cloud Shell，這是一種在 Google Cloud 中執行的指令列環境。Cloud Shell 是以 Debian 為基礎的虛擬機器，搭載各種您需要的開發工具。它提供永久的 5 GB 主目錄，可大幅提升網路效能和驗證。也就是說，在本程式碼研究室中，您只需要一支瀏覽器即可。

如要透過 Cloud 控制台啟用 Cloud Shell，請按照下列步驟操作：

  1. 按一下「啟用 Cloud Shell」圖示 a8460e837e9f5fda.png。

佈建並連線至環境的作業可能需要一點時間才能完成。

啟用 Cloud Shell 選項。

Cloud Shell 顯示指令列提示。

連線至 Cloud Shell 後，您應會發現自己通過驗證，且專案已設為 PROJECT_ID。

  1. 產生具有憑證的帳戶清單：
gcloud auth list

您應該會看到下列輸出內容：

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)
  1. 如要查看專案清單，請輸入此指令。
gcloud config list project

您應該會看到下列輸出內容：

[core]
project = <PROJECT_ID>

如因故未設定專案，請執行下列指令來設定專案。

gcloud config set project <PROJECT_ID>

PROJECT_ID 是您在設定步驟中使用的 ID。您也可以透過 Cloud 控制台資訊主頁查看這項資訊：

顯示專案 ID 的專案資訊窗格。

根據預設，Cloud Shell 也會設定一些環境變數，這在您日後執行指令時可能會很實用。

  1. 如要查看專案 ID，請輸入下列指令。
echo $GOOGLE_CLOUD_PROJECT

您應該會看到以下的輸出內容：

<PROJECT_ID>
  1. 最後，進行預設可用區和專案設定。
gcloud config set compute/zone us-central1-f

您可以選擇各種不同的可用區。詳情請參閱「區域和可用區」一文。

3. 從專案呼叫 API

本程式碼研究室將說明如何使用範例 API (Natural Language API) 尋找文字中的實體 (例如人物、地點和事件)，並說明如何估算該文字的情緒 (好感度)。您會瞭解如何執行下列作業：

  • 啟用 Google Cloud API。
  • 透過 API 金鑰和服務帳戶取得 API 相關授權。
  • 使用 curl 和用戶端程式庫呼叫 API。

啟用 API

  1. 選取「API 與」服務。

顯示 API 和 Cloud 控制台的 Cloud 控制台主選單服務選項。

  1. 選取畫面頂端的「+ 啟用 API 和服務」。

。

  1. 此時，您可以篩選及瀏覽 API，或直接使用搜尋方塊前往 API。搜尋 Natural Language 並選取「Cloud Natural Language API」。

Cloud Natural Language API 窗格顯示「啟用」和「試用這個 API」按鈕。

  1. 按一下「試用這個 API」。

如未顯示「試用這個 API」按鈕，請點選列出的任一方法，試用該方法。

建立 API 金鑰

由於您使用 curl 將要求傳送至 Natural Language API，因此必須產生 API 金鑰以傳送要求網址。

  1. 在 Cloud 控制台中，依序選取「導覽選單」>API 與服務 >憑證。

顯示 API 和 API 的導覽選單服務和憑證選項。

  1. 按一下「建立 CREDENTIALS」，然後選取「API key」：

「憑證」窗格顯示「建立憑證」和「API 金鑰」選項。

  1. 複製系統產生的 API 金鑰，然後按一下「關閉」。

使用 API 金鑰呼叫 API

  1. 在 Cloud Shell 指令列中匯出 API 金鑰。
export API_KEY=<YOUR_API_KEY>

將 <YOUR_API_KEY> 替換為您先前產生的金鑰。

  1. 使用 Cloud Shell 編輯器或 Linux 編輯器 (例如 Vim 或 Emacs) 建立 API 要求。如要進一步瞭解參數，請參閱Method: document.analyzeEntities。將輸出內容儲存至名為 request.json 的檔案：
{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}
  1. 使用要求資訊呼叫 API。
curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json
  1. 重新執行指令，並將輸出內容重新導向至檔案，然後檢查結果。如需 JSON 檔案的輸出詳細資料，請參閱 Method: document.analyzeEntities。
  2. 如要變更 request.json 檔案中要分析的文字，請將 content 值替換為您選擇的文字。

4. 使用服務帳戶授權

服務帳戶通常會提供驗證和授權，因此通常比 API 金鑰更適合。您可以將服務帳戶視為應用程式的電子郵件地址，

  1. 返回 API 與服務選單。
  2. 選取「建立憑證」，但這次請選取「服務帳戶」。

服務帳戶詳細資料窗格。

  1. 提供服務帳戶名稱來說明其用途，例如「Natural Language Service Account」。系統會建議 ID。你也可以新增說明。進一步瞭解服務帳戶時，您會提供服務帳戶存取專案的權限，並向使用者授予該服務帳戶的存取權，但目前請先點選「完成」來建立服務帳戶。
  2. 如要為服務帳戶建立金鑰組，請按一下 d489bd059474ae59.png 來編輯服務帳戶。

「Service accounts」(服務帳戶) 窗格顯示帳戶清單。

畫面上隨即會顯示服務帳戶的詳細資料。

顯示 Natural Language 服務帳戶詳細資料的服務帳戶詳細資料窗格。

  1. 複製服務帳戶的電子郵件地址，然後返回 Cloud Shell。
  2. 在 Cloud Shell 中，為服務帳戶建立金鑰組，並設定指向該金鑰組的環境變數：
gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud 會使用這個環境變數來尋找憑證，因此不需要包含在 API 呼叫中。

  1. 您現在可以使用下列指令呼叫 API：
gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'."

結果應與先前相同。

許多 API 都有大量的用戶端程式庫，可用來擷取這些詳細資料。如要進一步瞭解用戶端程式庫，請參閱 Cloud 用戶端程式庫。您也可以參閱所用 API 的說明文件，瞭解自己的 API 有哪些可用的用戶端程式庫。

5. 清除所用資源

對於專案來說，使用未受限制的 API 金鑰會是不理想的做法。只要有人取得存取權，對方即可使用該檔案，無需再進行驗證。

刪除這組 API 金鑰的步驟如下：

  1. 按一下 f6b6844bf5688982.png 導覽選單 >API 與服務 >憑證。
  2. 在「API 金鑰」下方，選取要刪除的金鑰，然後按一下 247adf2e1d1eae4b.png「刪除」。
  3. 同樣地，無須擔心服務帳戶私密金鑰未受到保護，請在「服務帳戶」下方選取要刪除的服務帳戶，然後按一下 247adf2e1d1eae4b.png「刪除」。

6. 恭喜

恭喜！您已瞭解如何建立 Google Cloud 專案，以及如何在專案中呼叫 API。