本頁面由 Cloud Translation API 翻譯而成。

快速入門導覽課程：使用 gcloud CLI 保護傳送至服務的流量

本頁面說明如何在 API Gateway 上部署 API，確保後端服務的流量安全。

請按照下列步驟，使用 Google Cloud CLI 部署新 API，存取 Cloud Run functions 上的後端服務。本快速入門導覽課程也會說明如何使用 API 金鑰，保護後端免於未經授權的存取。

事前準備

在 Google Cloud 控制台中，前往「資訊主頁」頁面，然後選取或建立 Google Cloud 專案。
前往資訊主頁

注意： 如果您不打算保留在本快速入門中建立的資源，請建立新的專案，不要選擇現有的專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。
確認專案已啟用計費功能。
啟用計費功能
確認 Google Cloud CLI 已下載並安裝在電腦上。
下載 gcloud CLI
更新 gcloud 元件：
```
gcloud components update
```
設定預設專案。將 PROJECT_ID 替換為專案 ID。 Google Cloud
```
gcloud config set project PROJECT_ID
```

啟用必要服務

API Gateway 需要啟用下列 Google 服務：

名稱	標題
`apigateway.googleapis.com`	API Gateway API
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

請使用下列指令啟用這些服務：

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

如要進一步瞭解 gcloud 服務，請參閱 gcloud 服務。

部署 API 後端

API Gateway 位於已部署的後端服務前方，負責處理所有傳入的要求。在本快速入門導覽課程中，API 閘道會將來電轉送至名為 helloGET 的 Cloud Run 函式後端，其中包含下列函式：

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

按照「快速入門：使用 Google Cloud CLI」一文中的步驟，下載範例 Cloud Run 函式程式碼，並部署 Cloud Run 函式後端服務。

建立 API

現在您已準備好在 API Gateway 中建立 API。

輸入下列指令，其中：
- API_ID 會指定 API 的名稱。如需 API 命名規範，請參閱「API ID 規定」。
```
gcloud api-gateway apis create API_ID 
```
例如：
```
gcloud api-gateway apis create my-api
```

成功完成後，您可以使用下列指令查看新 API 的詳細資料：

gcloud api-gateway apis describe API_ID

例如：

gcloud api-gateway apis describe my-api

這項指令會傳回下列內容：

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

請記下 managedService 屬性的值。這個值會在後續步驟中用於啟用 API。

建立 API 設定

API Gateway 必須先取得 API 設定，才能管理傳送至部署 API 後端的流量。

您可以使用包含特殊註解的 OpenAPI 說明建立 API 設定，定義所選的 API Gateway 行為。如要進一步瞭解支援的 OpenAPI 擴充功能，請參閱下列說明：

本快速入門導覽課程使用的 OpenAPI 說明包含 Cloud Run 函式後端的轉送指示：

OpenAPI 2.0

# openapi-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

如要上傳這份 OpenAPI 說明，並使用 gcloud CLI 建立 API 設定，請按照下列步驟操作：

從指令列建立名為 openapi-functions.yaml 的新檔案。
複製 OpenAPI 說明的內容，並貼到新建立的檔案中。
編輯檔案，如下所示：
1. 在 title 欄位中，將 API_ID 替換為 API 名稱，並將 optional-string 替換為您選擇的簡要說明。這個欄位的值用於鑄造 API 金鑰，授予這個 API 的存取權。
2. 在 address 欄位中，將 GATEWAY_LOCATION 替換為已部署函式的 Google Cloud 區域，並將 PROJECT_ID 替換為專案的 Google Cloud 名稱。
輸入下列指令，其中：
- CONFIG_ID 指定 API 設定的名稱。
- API_ID 會指定 API 的名稱。
- API_DEFINITION 指定 OpenAPI 規格的檔案名稱。
- SERVICE_ACCOUNT_EMAIL：指定用於為已設定驗證的後端簽署權杖的服務帳戶。詳情請參閱「設定服務帳戶」。
  注意：用於為 Cloud Run functions 後端建立 API 設定的服務帳戶，必須已指派 cloudfunctions.invoker 角色。
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
例如：
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
API 設定會傳播至下游系統，因此這項作業可能需要幾分鐘才能完成。建立複雜的 API 設定最多可能需要十分鐘。

注意：如果執行這項指令時收到 FAILED_PRECONDITION: Service Account ... does not exist 形式的錯誤，請參閱「設定服務帳戶」，確認專案已啟用服務帳戶。
注意：針對特定 API，一次只能建立一個 API 設定。請等待設定建立完成，再嘗試為相同 API 建立新設定。

API 設定建立完成後，執行下列指令即可查看詳細資料：

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

例如：

gcloud api-gateway api-configs describe my-config \
  --api=my-api

輸出內容會顯示您的 API 設定詳細資料，包括名稱和狀態，如下例所示：

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

建立閘道

現在，請在閘道上部署 API 設定。在閘道上部署 API 設定時，會定義 API 用戶端可用來存取 API 的外部網址。

執行下列指令，將您剛建立的 API 設定部署至 API Gateway：

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

其中：

GATEWAY_ID 會指定閘道的名稱。
API_ID 指定與這個閘道相關聯的 API Gateway API 名稱。
CONFIG_ID 指定部署至閘道的 API 設定名稱。
GCP_REGION 是已部署閘道的Google Cloud 地區。
注意：
有效值為：
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
PROJECT_ID 指定 Google Cloud 專案的名稱。

例如：

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1

成功完成後，請使用下列指令查看閘道詳細資料：

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

例如：

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1

這項指令會傳回下列內容：

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

請記下 defaultHostname 屬性的值。這是您在下一個步驟中用來測試部署作業的閘道網址主機名稱部分。

測試 API 部署作業

現在，您可以使用部署閘道時產生的網址來傳送要求至 API。

輸入下列 curl 指令，其中：

DEFAULT_HOSTNAME：指定已部署閘道網址的主機名稱部分。
hello 是 API 設定中指定的路徑。

curl https://DEFAULT_HOSTNAME/hello

例如：

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

輸出內容會如下所示：

Hello World!

您已成功建立及部署 API Gateway！

使用 API 金鑰確保存取安全

如要安全地存取 API 後端，請產生與專案相關聯的 API 金鑰，並授予該金鑰呼叫 API 的存取權。詳情請參閱「使用 API 金鑰限制 API 存取權」。

如果您還沒有與本快速入門導覽課程所用 Google Cloud 專案相關聯的 API 金鑰，可以按照「建立 API 金鑰」一文中的步驟新增金鑰。

如要使用 API 金鑰確保閘道存取安全，請按照下列步驟操作：

為服務啟用 API 金鑰支援功能。輸入下列指令，其中：
- MANAGED_SERVICE_NAME 是指您部署 API 時建立的代管服務名稱。您可以使用 gcloud apigee-gateway apis describe 指令查看列出的 Managed Service 屬性。
- PROJECT_ID 指定 Google Cloud 專案的名稱。
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
舉例來說：
```
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
```

修改用來建立 API 設定的 OpenAPI 說明，加入對所有流量強制執行 API 金鑰驗證安全性政策的指令。新增 security 類型和 securityDefinitions，如下所示：

OpenAPI 2.0

  # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

當要求存取規格中定義的所有路徑時，securityDefinition 會將您的 API 設定為要求以名為 key 的查詢參數形式傳遞 API 金鑰。

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

當要求存取規格中定義的所有路徑時，securitySchemes 會將您的 API 設定為要求以名為 key 的查詢參數形式傳遞 API 金鑰。

使用下列指令，以修改後的 OpenAPI 規格建立新的 API 設定：

gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

舉例來說：

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

執行下列指令，以新的 API 設定更新現有閘道：

gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION

舉例來說：

gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1

測試 API 金鑰

建立並部署修改後的 API 之後，請嘗試提出要求。

輸入下列 curl 指令，其中：

DEFAULT_HOSTNAME：指定已部署閘道網址的主機名稱部分。
hello 是 API 設定中指定的路徑。

curl https://DEFAULT_HOSTNAME/hello

例如：

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

這應該會產生下列錯誤：

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

現在請輸入下列 curl 指令，其中：

DEFAULT_HOSTNAME：指定已部署閘道網址的主機名稱部分。
hello 是 API 設定中指定的路徑。
API_KEY 指定您在前一個步驟中建立的 API 金鑰。

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

現在您應該會在 API 的回應中看到 Hello World!。

恭喜！您已成功使用 API Gateway 保護 API 後端。現在您可以產生其他 API 金鑰，開始加入新的 API 用戶端。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取這個快速入門導覽課程所用資源的費用，您可以：

或者，您也可以刪除 Google Cloud 本教學課程中使用的專案。

後續步驟

進一步瞭解 API Gateway
逐步完成「設定開發環境」一節
瞭解服務之間的驗證