GSP294

總覽

應用程式設計介面 (API) 是一種軟體程式，可讓開發人員存取運算資源和資料。許多不同領域的公司都提供公開 API，開發人員能將專門工具、服務或程式庫整合至自家應用程式和程式碼集。

本實驗室將帶您複習 API 的架構和基本運作方式。此外，您還能透過實作練習，在 Google Cloud Shell 設定及執行 Cloud Storage API 方法。完成本實驗室後，您將瞭解 API 通訊、架構和驗證的重要原則。您還能獲得 API 實務經驗，可應用於未來的實驗室或專案。

API - 什麼是 API？為何要使用 API？

讓開發人員存取資料和運算資源，可大幅提升工作效率。比從頭建構每個程式、方法或資料集，使用 API 容易得多。API 的建構原則是抽象化，也就是說，您不必瞭解 API 的內部運作方式或複雜性，就能應用在自家環境。

API 是專為開發人員打造，通常不提供圖形使用者介面 (GUI)。不過，這項慣例也有例外。Google 近期推出一項新工具 APIs Explorer，可讓您以互動方式探索各種 Google API。如想進一步瞭解，請務必接著完成 APIs Explorer：Qwik Start 實驗室。

Cloud API

Google 提供多種 API，可應用於不同領域和產業。API 常見於網頁開發、機器學習、資料科學和系統管理工作流程。不過，這些只是少數應用實例。舉例來說，瀏覽 AnyAPI 後，您會發現還有許多 API 應用方式。

Qwiklabs 為實驗室執行個體佈建新的 Google Cloud 專案時，會在背景啟用大多數 API，讓您立即著手進行實驗室任務。如果您在 Qwiklabs 以外的環境建立自己的專案，必須自行啟用某些 API。

隨著您對 Google Cloud 的使用越來越熟練，工作流程中會用到更多 API。經驗豐富的使用者幾乎只在本機環境整合及使用 Cloud API，很少透過 Cloud 控制台執行工具和服務。我們提供數十個實作實驗室，讓您練習以不同語言使用各種 Google API。

在本實驗室中，您將瀏覽 API 程式庫，瞭解有哪些 Google API 可派上用場。

目標

本實驗室的內容包括：

• Google API
• API 架構
• HTTP 通訊協定和方法
• 端點
• REST (具象狀態傳輸) 和符合 REST 樣式的 API
• JSON (JavaScript 物件標記法)
• API 驗證服務

事前準備

這是入門等級的實驗室，預設對象為 API 使用經驗不多或未曾用過 Google API 的使用者。建議您熟悉殼層環境和指令列介面工具，但這並非必要條件。建議您熟悉 Cloud 控制台和 Cloud Storage，因此請至少完成下列實驗室，再進行本實驗室：

• Qwiklabs 和 Google Cloud 導覽
• Cloud Storage：Qwik Start - Cloud 控制台

準備完成後，即可向下捲動頁面，按照步驟設定實驗室環境。

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

啟動 Cloud Shell

Cloud Shell 是搭載多項開發工具的虛擬機器，提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權，方便您使用 Google Cloud 資源。

1. 點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示 。

2. 系統顯示視窗時，請按照下列步驟操作：

   • 繼續操作 Cloud Shell 視窗。
   • 授權 Cloud Shell 使用您的憑證發出 Google Cloud API 呼叫。

連線建立完成即代表已通過驗證，而且專案已設為您的 Project_ID：。輸出內容中有一行文字，宣告本工作階段的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的指令列工具，已預先安裝於 Cloud Shell，並支援 Tab 鍵自動完成功能。

3. (選用) 您可以執行下列指令來列出使用中的帳戶：

gcloud auth list

4. 點按「授權」。

輸出內容：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (選用) 您可以使用下列指令來列出專案 ID：

gcloud config list project

輸出內容：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需 gcloud 的完整說明，請前往 Google Cloud 參閱 gcloud CLI 總覽指南。

設定專案區域

請執行以下指令來設定專案區域：

gcloud config set compute/region {{{project_0.default_region | Region}}}

API 的運作方式

API 架構

應用程式設計介面 (API) 是一組方法，可讓程式相互通訊。為了有效通訊，程式必須遵守明確的通訊協定，該協定規範資料的傳輸和解讀。網際網路是 API 用來在程式之間傳輸要求和回應的標準通訊管道。網路型 API 使用用戶端伺服器模型做為交換資訊的基礎架構。用戶端是提出運算資源或資料要求的運算裝置，伺服器則儲存資料和/或運算資源，並負責解讀並滿足用戶端的要求。

HTTP 通訊協定和方法

由於 API 使用網路做為通訊管道，因此許多 API 都遵循 HTTP 通訊協定，該協定指定了用戶端和伺服器透過網際網路交換資料的規則和方法。使用 HTTP 通訊協定的 API 會採用 HTTP 要求方法 (也稱為「HTTP 動詞」)，將用戶端要求傳送至伺服器。最常用的 HTTP 要求方法是 GET、POST、PUT 和 DELETE。GET 用於用戶端從伺服器擷取資料，PUT 用於取代現有資料，或在資料不存在時建立資料，POST 主要用於建立新資源，DELETE 則用於移除用戶端在伺服器指定的資料或資源。

端點

API 會使用 HTTP 方法與伺服器上的資料或運算服務互動，但如果無法穩定存取特定資源，這些方法就毫無用處。因此 API 會使用稱為端點的通訊管道，讓用戶端能順利存取所需資源。端點是託管於伺服器上的資料或運算資源存取點，形式為 HTTP URI。端點會新增至 API 的基本網址，以建立特定資源或資源容器的路徑。此外，您還可以在端點加入查詢字串，傳入完成 API 要求所需的變數。

REST 和符合 REST 樣式的 API

使用 HTTP 通訊協定、要求方法和端點的 API 稱為「符合 REST 樣式的 API」。符合 REST 樣式的 API 位於伺服器，負責實作用戶端要求。這個模型定義了端點 (名詞) 框架，HTTP 方法 (動詞) 會對這些端點執行動作，API 則會使用這個框架來滿足要求。總結來說，符合 REST 樣式的 API 採用用戶端伺服器模型、遵循 HTTP 通訊協定、使用 HTTP 要求方法，並透過端點存取特定資源。

隨堂測驗

請回答下列選擇題，充分理解目前為止學到的概念。

工作 1：使用 API 程式庫

在本節中，您將探索 API 程式庫並啟用 API。API 程式庫集中存放所有 Google API。您可以使用 API 程式庫，在各專案中啟用、停用及管理 API。

1. 開啟「導覽選單」，依序選取「API 和服務」>「程式庫」。

API 程式庫提供 200 多個 Google API 的快速存取權、說明文件和設定選項。雖然這個程式庫位於控制台中，但請注意，它提供「所有 Google API」的存取權，不是只有 Google Cloud 相關的 API。這點突顯出一個重點：API 是所有 Google 服務的基礎，而 Cloud API 並非都屬於 Google Cloud 類別。

現在來實際練習，在 API 程式庫啟用 API。假設您是健身網站的行動版開發人員，想使用 Google Fitness API 建構應用程式。

2. 在「Search for APIs and Service」搜尋列輸入 Fitness API，然後按下 Enter 鍵。
3. 在結果清單點選「Fitness API」，接著點按「啟用」。

「Fitness API」頁面會隨即開啟，API 的狀態為「已啟用」。

API 程式庫提供各類連結，供您前往瀏覽教學課程和說明文件、服務條款，以及 APIs Explorer 中提供的互動式方法。如要查看指標和用量資訊，請使用「API 和服務」資訊主頁。您可以在這個頁面查看及要求配額、控管資源和資料的存取權，以及查看指標。

4. 如要查看這些功能的實際運作情形，請選取「配額與系統限制」分頁標籤。

5. 這會顯示此 API 每日和每分鐘允許的查詢數量。

您已佈建非 Cloud API。在接下來的章節，您將瞭解 API 的架構和基本運作方式，接著練習使用 Cloud Storage API。

隨堂測驗

請回答下列選擇題，充分理解目前為止學到的概念。

工作 2：在 Cloud 控制台建立 JSON 檔案

為了應用所學，請在 Cloud Shell 呼叫 Cloud Storage REST/JSON API，建立 bucket 並上傳內容。

1. 在新分頁開啟 Google Cloud Storage JSON API，確認 Cloud Storage API 已啟用。注意 API 已啟用。

2. 在 Cloud Shell 執行下列指令，建立並編輯 values.json 檔案：

nano values.json

3. 在 nano 文字編輯器，複製並貼上下列內容。由於 bucket 名稱必須獨一無二，因此 bucket 名稱中會使用專案 ID：

{ "name": "{{{project_0.project_id | Project_ID}}}-bucket", "location": "us", "storageClass": "multi_regional" } 注意：由於專案 ID 在全域中是獨一無二的，因此您可以將專案 ID 做為 bucket 名稱。

4. 完成後，依序按下 CTRL+X、Y 和 ENTER 鍵，退出 nano 文字編輯器。

您剛建立的 JSON 檔案包含一個物件，其中有三個鍵/值組合：name、location 和 storageClass。您使用 gsutil 指令列工具或在控制台中建立 bucket 時，也需要使用上述值。

使用 Cloud Storage REST/JSON API 建立 bucket 前，您需要先設定適當的驗證和授權政策。

工作 3：驗證 Cloud Storage JSON/REST API 並授予權限

驗證及授權

驗證和授權是經常交替使用的兩個詞彙，但兩者意義不同。

• 「驗證」是判定用戶端身分的程序。
• 「授權」程序則是，判斷經過驗證的用戶端對一組資源具備哪些權限。

驗證會判斷您的身分，授權則決定您可以執行哪些操作。

Google API 使用三種驗證/授權服務，包括「API 金鑰」、「服務帳戶」和「OAuth」。API 會根據要求資源和呼叫來源，使用其中一種驗證服務。

API 金鑰

API 金鑰是密鑰權杖，通常以加密字串的形式提供，可快速產生及使用。使用公開資料或方法的 API，通常會以 API 金鑰快速驗證使用者身分，讓開發人員快速上手。

在 Google Cloud 中，API 金鑰用於識別呼叫 API 的專案。API 金鑰能藉由辨識呼叫的專案，啟用使用資訊並與該專案建立關聯，甚至可以拒絕來自於非授權存取或尚未啟用 API 的專案呼叫。

OAuth

OAuth 權杖的格式與 API 金鑰類似，但安全性更高，且可連結至使用者帳戶或身分。API 提供開發人員存取使用者資料的管道時，是這些權杖主要使用時機。

API 金鑰可讓開發人員存取 API 的所有功能，而 OAuth 用戶端 ID 則以範圍為依據，不同身分會獲得不同的權限。

服務帳戶

服務帳戶是一種特殊的 Google 帳戶類型，屬於您的應用程式或虛擬機器 (VM)，而不屬於個別使用者。您的應用程式以服務帳戶的身分呼叫 Google API，如此一來使用者即不會直接參與其中。

透過向應用程式提供服務帳戶私密金鑰，或是在 Cloud Function、Google App Engine、Compute Engine 或 Google Kubernetes Engine 執行時使用提供的內建服務帳戶，您就可以使用服務帳戶。

如要瞭解服務帳戶和角色的相關實驗室，請參閱：服務帳戶與角色：基礎知識。

Cloud Storage 是用於代管及提供使用者資料存取權的平台，因此您必須先產生 OAuth 權杖，才能使用其服務。

1. 在新分頁開啟 OAuth 2.0 Playground。這項服務可讓您輕鬆產生 OAuth 權杖。

2. 向下捲動並選取「Cloud Storage API V1」。

3. 然後選取 https://www.googleapis.com/auth/devstorage.full_control 範圍。

4. 點選藍色方塊中的「Authorize APIs」。Google 登入頁面隨即開啟。

5. 選取使用者名稱，然後在系統提示授予權限時，點選「允許」。

OAuth 2.0 Playground 會開啟，請注意步驟 2 已產生授權碼。

6. 這時請按一下「Exchange authorization code for tokens」。如果系統將您移至步驟 3，請點選步驟 2 面板。

7. 複製存取權杖，以便在下一步使用。

工作 4：使用 Cloud Storage JSON/REST API 建立 bucket

1. 返回 Cloud Shell 工作階段。在 CLI 提示中輸入 ls，然後按下 Enter 鍵。您應該會看到先前建立的 values.json 檔案和 README-cloudshell.txt 檔案：

輸出：

README-cloudshell.txt values.json

2. 執行下列指令，將 OAuth2 權杖設為環境變數，並將 <YOUR_TOKEN> 替換為您產生的存取權杖：

export OAUTH2_TOKEN=<YOUR_TOKEN>

3. 執行下列指令，將專案 ID 設為環境變數：

export PROJECT_ID=$(gcloud config get-value project)

4. 接著執行下列指令，建立 Cloud Storage bucket：

curl -X POST --data-binary @values.json \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://www.googleapis.com/storage/v1/b?project=$PROJECT_ID"

5. 畫面上會顯示類似下方的輸出內容：

{ "kind": "storage#bucket", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7", "id": "qwiklabs-gcp-02-5d551758b5a7", "name": "qwiklabs-gcp-02-5d551758b5a7", "projectNumber": "670840659006", "metageneration": "1", "location": "US", "storageClass": "MULTI_REGIONAL", "etag": "CAE=", "timeCreated": "2020-11-11T06:41:40.901Z", "updated": "2020-11-11T06:41:40.901Z", "iamConfiguration": { "bucketPolicyOnly": { "enabled": false }, "uniformBucketLevelAccess": { "enabled": false } }, "locationType": "multi-region" } 注意：如果收到「Use of this bucket name is restricted」或「Sorry, that name is not available」等錯誤訊息，表示該名稱與通用 bucket 命名慣例衝突。編輯 values.json 檔案，替換 bucket 名稱。

這項要求濃縮了您目前所學的內容。您使用 curl CLI 工具發出 HTTP POST 方法要求。您將 values.json 檔案傳遞至要求主體。您已將 OAuth 權杖和 JSON 規格做為要求標頭傳遞。這項要求已轉送至 Cloud Storage 端點，其中包含設為專案 ID 的查詢字串參數。

查看新建立的 Cloud Storage bucket

• 依序選取「導覽選單」>「Cloud Storage」>「Bucket」，即可查看新建立的 bucket。

測試已完成的工作

點選「Check my progress」，確認工作已完成。如果使用 Cloud Storage JSON/REST API 成功建立 bucket，評估分數就會更新。

使用 Cloud Storage JSON/REST API 建立 bucket

工作 5：使用 Cloud Storage JSON/REST API 上傳檔案

您可以使用 Cloud Storage JSON/REST API，將檔案上傳至 bucket。

1. 將下列圖片儲存至電腦，並命名為 demo-image.png：

2. 在 Cloud Shell 工作階段，按一下右上角的三點選單圖示。依序點選「上傳」 >「選擇檔案」。選取並上傳 demo-image.png 檔案。圖片就會新增至目錄。

3. 執行下列指令，取得圖片的路徑：

realpath demo-image.png

畫面上會顯示類似下方的輸出內容：

/home/gcpstaging25084_student/demo-image.png

4. 執行下列指令，將檔案路徑設為環境變數，並將 <DEMO_IMAGE_PATH> 替換為先前指令的輸出內容：

export OBJECT=<DEMO_IMAGE_PATH>

5. 執行下列指令，將 bucket 名稱設為環境變數：

export BUCKET_NAME={{{project_0.project_id | Project_ID}}}-bucket

6. 現在執行下列指令，將示範圖片上傳至 Cloud Storage bucket：

curl -X POST --data-binary @$OBJECT \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: image/png" \ "https://www.googleapis.com/upload/storage/v1/b/$BUCKET_NAME/o?uploadType=media&name=demo-image"

畫面上會顯示類似下方的輸出內容：

{ "kind": "storage#object", "id": "qwiklabs-gcp-02-5d551758b5a7/demo-image/1605077118178936", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image", "mediaLink": "https://www.googleapis.com/download/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image?generation=1605077118178936&alt=media", "name": "demo-image", "bucket": "qwiklabs-gcp-02-5d551758b5a7", "generation": "1605077118178936", "metageneration": "1", "contentType": "image/png", "storageClass": "MULTI_REGIONAL", "size": "401951", "md5Hash": "LbpHpwhnApQKQx9IEXjTsQ==", "crc32c": "j5oPrg==", "etag": "CPis3Zvy+ewCEAE=", "timeCreated": "2020-11-11T06:45:18.178Z", "updated": "2020-11-11T06:45:18.178Z", "timeStorageClassUpdated": "2020-11-11T06:45:18.178Z" }

7. 如要查看新增至 bucket 的圖片，請開啟導覽選單，依序選取「Cloud Storage」>「Bucket」。

8. 點選 bucket 名稱，確認 demo-image 已新增：

9. 按一下圖片名稱，開啟「物件詳細資料」頁面。

測試已完成的工作

點選「Check my progress」，確認工作已完成。如果使用 Cloud Storage JSON/REST API 成功上傳檔案，評估分數就會更新

使用 Cloud Storage JSON/REST API 上傳檔案

恭喜！

在本實驗室中，您對 API 有了紮實的瞭解，並實際操作了 Cloud Storage JSON/REST API。您瞭解了 Cloud API、API 架構、HTTP 通訊協定和方法、端點、符合 REST 樣式的 API、JSON 和 API 驗證做法。您已經準備好在 Qwiklabs 參加其他 API 實驗室了！

後續步驟/瞭解詳情

請務必查看下列實驗室，把握更多 API 練習機會：

• APIs Explorer：Qwik Start
• Cloud Natural Language API：Qwik Start

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2024 年 2 月 26 日

實驗室上次測試日期：2024 年 2 月 26 日

Copyright 2025 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。