從 Google Cloud 專案呼叫 API

1. 事前準備

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

必要條件

• 能夠瀏覽 Google Cloud 控制台。

課程內容

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

軟硬體需求

• Google 帳戶，例如 Gmail 帳戶或 Google Workspace 帳戶。
• 存取 Cloud Billing 帳戶或信用卡，以便註冊免費試用方案。

2. 做好準備

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

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

注意：如果沒有 Gmail 帳戶或 Google Workspace 帳戶，請先建立帳戶。

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

警告：如果您重複使用專案並完成本程式碼研究室，在您完成後未關閉專案的情況下，部分使用者可能會存取該專案中的資源。

記下專案 ID，這組 ID 會顯示在「專案名稱」欄位下方。這個 ID 是所有 Google Cloud 專案中不重複的名稱 (上述名稱已遭占用)，在本程式碼研究室中會稱為 PROJECT_ID。

注意：如果使用 Gmail 帳戶，可以將預設位置設為「沒有機構」。如果你使用 Google Workspace 帳戶，請選擇適合貴機構的位置。

2. 接著，請在 Cloud Console 中啟用計費功能，以便使用 Google Cloud 資源。

雖然本程式碼研究室的費用不高，但為避免產生額外費用，請按照「清除」一節的指示關閉資源。請注意，Google Cloud 新使用者享有價值 $300 美元的免費試用期。

設定 Cloud Shell

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

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

1. 按一下 「Activate Cloud Shell」(啟用 Cloud Shell)。

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

連至 Cloud Shell 後，您應該會看到驗證已完成，專案也已設為獲派的專案 ID PROJECT_ID。

2. 產生已認證帳戶清單：

gcloud auth list

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

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

注意：Cloud Shell 預先安裝了 gcloud CLI 工具，可協助您建立及管理 Google Cloud 資源。詳情請參閱 gcloud 工具總覽。

3. 如要查看專案清單，請輸入下列指令。

gcloud config list project

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

[core]
project = <PROJECT_ID>

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

gcloud config set project <PROJECT_ID>

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

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

4. 如要查看專案 ID，請輸入下列指令。

echo $GOOGLE_CLOUD_PROJECT

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

<PROJECT_ID>

5. 最後，設定預設可用區和專案。

gcloud config set compute/zone us-central1-f

你可以選擇各種不同區域。詳情請參閱「地區和區域」。

注意：在電腦上執行 gcloud CLI 工具時，各個工作階段都會保留設定。不過，在 Cloud Shell 中，每次啟動新工作階段或重新連線時，都必須設定這些設定。

3. 從專案呼叫 API

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

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

啟用 API

1. 在 Cloud 控制台的主選單中，選取「API 和服務」。

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

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

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

如果沒有顯示「TRY THIS API」(試用這個 API) 按鈕，請點選列出的其中一個方法，試用該方法。

建立 API 金鑰

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

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

2. 按一下「CREATE CREDENTIALS」，然後選取「API key」：

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

使用 API 金鑰呼叫 API

1. 在 Cloud Shell 指令列中匯出 API 金鑰。

export API_KEY=<YOUR_API_KEY>

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

2. 在 Cloud Shell 編輯器中或使用 Linux 編輯器 (例如 Vim 或 Emacs) 建立 API 要求。如要瞭解參數詳細資料，請參閱「方法：documents.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"
}

3. 使用要求資訊呼叫 API。

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. 重新執行指令，將輸出內容重新導向至檔案，然後檢查結果。JSON 檔案輸出內容的詳細資料也位於「方法：documents.analyzeEntities」。
5. 如要變更 request.json 檔案中要分析的文字，請將 content 值替換為所選文字。

4. 使用服務帳戶授權

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

1. 返回「APIs & Services」(API 和服務) 選單的「憑證」部分。
2. 選取「建立憑證」，但這次請選取「服務帳戶」。

3. 提供可說明用途的服務帳戶名稱，例如「Natural Language Service Account」。系統會建議 ID。你也可以新增說明。進一步瞭解服務帳戶後，您會提供專案的服務帳戶存取權，並授予使用者服務帳戶存取權，但現在只要按一下「完成」，即可建立服務帳戶。
4. 如要為服務帳戶建立金鑰組，請按一下 編輯服務帳戶。

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

5. 複製服務帳戶的電子郵件地址，然後返回 Cloud Shell。
6. 在 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 呼叫。

7. 現在可以使用下列指令呼叫 API：

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

結果應與先前相同。

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

5. 清理

專案不應使用未受限制的 API 金鑰，如果有人取得存取權，就能使用這組密鑰，不必再進行驗證。

如要刪除這組 API 金鑰，請按照下列步驟操作：

1. 依序點選 「導覽選單」>「API 和服務」>「憑證」。
2. 在「API 金鑰」下方，選取要刪除的金鑰，然後按一下「刪除」。
3. 同樣地，您不必擔心服務帳戶私密金鑰未受保護，只要在「服務帳戶」下方選取要刪除的服務帳戶，然後按一下「刪除」圖示 即可。

6. 恭喜

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