建立 Cloud Tasks 佇列

本頁面說明如何建立 Cloud Tasks 工作佇列。工作新增至佇列後，佇列會調度工作，並確保工作由服務 (也稱為「worker」) 可靠地處理。

注意事項：

• 佇列名稱由三個部分組成：專案 ID、位置和佇列 ID。您必須擁有Google Cloud 專案，才能取得專案 ID。

• 如果您使用的是 App Engine 目標工作，則必須擁有位於特定區域的 App Engine 應用程式，也就是佇列和處理常式執行的位置。新增應用程式時，請留意區域。

  注意： 在 App Engine 指令中，europe-west 和 us-central 是兩個位置，在 Cloud Tasks 指令中則分別稱為 europe-west1 和 us-central1。

• 使用 HTTP 目標任務時，不需要 App Engine 應用程式。建立佇列時，請選取 Google Cloud 位置。

建立佇列

您可以透過下列方式建立佇列：

• 在 Google Cloud 控制台中
• 在終端機或 Cloud Shell 中使用 Google Cloud CLI
• 直接向 Cloud Tasks API 傳送要求

注意： 如果您要設定 App Engine 佇列的轉送功能，但未明確設定包含適當 worker 的目標服務，系統會使用預設服務。詳情請參閱「設定佇列轉送、限制和重試」。

控制台

1. 在 Google Cloud 控制台，依序前往「Cloud Tasks」>「Queues」(佇列) 頁面。

   前往「佇列」

2. 按一下 「Create queue」(建立佇列)。

3. 輸入佇列名稱，例如 my-queue。

4. 在「Region」(區域) 清單中，選取要執行佇列的支援位置，例如 asia-south1。

   如果貴組織限制資源位置，且您想在 us-central1 或 us-central2 建立佇列，組織政策必須允許在 us-central1 和 us-central2 建立佇列 (即使您只需要在其中一個區域建立佇列)。

5. 您也可以進一步設定佇列。

6. 點選「建立」。

gcloud

使用 gcloud tasks queues create 指令建立佇列：

  gcloud tasks queues create QUEUE_ID \
      --location=LOCATION

更改下列內容：

• QUEUE_ID：您指派給佇列的 ID，例如 my-queue。

• LOCATION：支援的區域，佇列會在此執行，例如 asia-south1。

  如果貴組織限制資源位置，且您想在 us-central1 或 us-central2 建立佇列，組織政策必須允許在 us-central1 和 us-central2 建立佇列 (即使您只需要在其中一個區域建立佇列)。

gcloud CLI 指令的其他旗標可讓您設定頻率限制、重試選項、佇列類型等。

REST API

如要建立佇列，請使用 projects.locations.queues.create 方法。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• LOCATION：執行佇列的支援區域，例如 asia-south1。

  如果貴組織限制資源位置，而您想在 us-central1 或 us-central2 建立佇列，組織政策必須允許在 us-central1 和 us-central2 建立佇列 (即使您只需要在其中一個區域建立佇列)。

• QUEUE_ID：您指派給佇列的 ID，例如 my-queue。

Queue 資源的其他可設定屬性包括頻率限制、重試選項、佇列類型等。

JSON 要求內文：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}
EOF

接著執行下列指令，傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著執行下列指令，傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求主體，然後開啟方法參考頁面。APIs Explorer 面板會在頁面右側開啟。 您可以與這項工具互動，傳送要求。 將要求主體貼到這項工具中，填寫其他必填欄位，然後按一下「Execute」。

如果成功，回應主體會包含新建立的 Queue 執行個體：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
  "rateLimits": {
    "maxDispatchesPerSecond": 500,
    "maxBurstSize": 100,
    "maxConcurrentDispatches": 1000
  },
  "retryConfig": {
    "maxAttempts": 100,
    "minBackoff": "0.100s",
    "maxBackoff": "3600s",
    "maxDoublings": 16
  },
  "state": "RUNNING"
}

新建立的佇列可能需要幾分鐘才能使用。

描述佇列

您可以透過下列方式，確認佇列是否已成功建立：

• 在 Google Cloud 控制台中
• 在終端機或 Cloud Shell 中使用 gcloud CLI

• 直接向 Cloud Tasks API 傳送要求

控制台

1. 在 Google Cloud 控制台，依序前往「Cloud Tasks」>「Queues」(佇列) 頁面。

   前往「佇列」

   綠色勾號 表示佇列正在執行。

2. 如要查看更多詳細資料，請按一下佇列名稱，然後按一下「Configuration」(設定) 分頁標籤。

gcloud

使用 gcloud tasks queues describe 指令，確認佇列已成功建立：

gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

更改下列內容：

• QUEUE_ID：佇列 ID (簡稱)
• LOCATION：佇列的位置

畫面會顯示如下的輸出內容：

name: projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: 1000
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

REST API

如要擷取佇列，請使用 projects.locations.queues.get 方法。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• LOCATION：部署佇列的區域，例如 us-central1。
• QUEUE_ID：佇列的簡短 ID，例如 my-queue。

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

開啟方法參考頁面。APIs Explorer 面板會在頁面右側開啟。 您可以與這項工具互動，傳送要求。 填寫所有必填欄位，然後按一下「Execute」(執行)。

如果成功，回應主體會包含 Queue 的執行個體：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
  "rateLimits": {
    "maxDispatchesPerSecond": 500,
    "maxBurstSize": 100,
    "maxConcurrentDispatches": 1000
  },
  "retryConfig": {
    "maxAttempts": 100,
    "minBackoff": "0.100s",
    "maxBackoff": "3600s",
    "maxDoublings": 16
  },
  "state": "RUNNING"
}

排解建立佇列的問題

注意： 系統預設不會啟用佇列記錄功能。如要瞭解如何啟用記錄功能，請參閱「搭配使用 Cloud Logging 和佇列」。

如果未看到預期的輸出內容，可以嘗試下列做法：

• 等待至少一分鐘的時間，讓佇列完成初始化。

• 確認尚未存在相同 ID 的佇列。您可以使用 gcloud tasks queues list 指令，查看專案中的佇列：

  gcloud tasks queues list \
      --location=LOCATION

  如要搜尋多個地點，則須提出多項要求。

• 檢查是否已達佇列配額：

  1. 在 Google Cloud 控制台中，前往 Cloud Tasks API 的「API/Service Details」(API/服務詳細資料) 頁面。

     前往「API/Service Details」(API/服務詳細資料) 頁面

  2. 按一下「配額與系統限制」分頁標籤。

  3. 如要提高配額，請在配額列中依序按一下省略符號圖示 >「Edit quota」(編輯配額)。

     詳情請參閱「要求調整配額」。

• 重新執行指令來建立佇列，並確保每個步驟都正確完成。

後續步驟

• 設定佇列轉送、限制和重試
• 建立 Cloud Tasks 工作
• 設定工作的重試參數
• 管理佇列和工作