本頁說明如何建立「工作處理常式」,也就是處理發送工作的程式碼。您必須提供要求處理常式,才能處理該工作。從要求網址到適當處理常式的對應,是在服務的app.yaml中宣告,就像任何其他要求處理常式一樣。由於是您控制如何將工作要求對應至處理常式,因此您可以直接整理工作處理常式。如果您的應用程式會處理多種不同種類的工作,您可以將所有處理常式新增至單一服務,或發布至多個服務中。
撰寫發送工作要求處理常式
在佇列中,工作佇列服務會建立 HTTP 標頭,並傳送至工作目標指定的工作站服務執行個體。工作佇列要求是從 IP 位址 0.1.0.2 傳送。
當您在不同的服務中使用處理常式時,並不需要使用當初建立工作並將工作排入佇列所用的語言。
撰寫處理常式時,請遵循以下準則:
程式碼必須傳回 200–299 範圍內的 HTTP 狀態碼來表示成功。如果傳回其他狀態碼,則表示工作失敗。
推送任務有固定的完成期限,取決於執行任務的服務擴充類型。自動調度資源服務必須在 10 分鐘內完成。手動和基本級服務最多可執行 24 小時。如果您的處理常式超過期限,工作佇列服務會認定該工作失敗,並再次執行該工作。
當工作的執行時間接近期限時,App Engine 會在期限前引發
DeadlineExceededError(來自模組google.appengine.runtime),讓您儲存工作或記錄任何進度。處理常式必須冪等。App Engine 的工作佇列 API 旨在提供「至少一次」傳遞;也就是說,如果成功新增任務,App Engine 會將任務傳遞至處理常式至少一次。請注意,在極少數情況下,可能會發生多次執行工作的情況,所以必須確保您的程式碼在重複執行時不會有任何有害的副作用。
工作佇列會使用處理常式回應中的 HTTP 代碼,來判斷工作是否成功完成。處理常式的回應只會由工作佇列服務查看,且僅用於判斷工作是否成功。佇列會忽略回應中的其他所有欄位,接著服務會捨棄回應。來源應用程式永遠接收不到任何資料。如果工作失敗,工作佇列服務會傳送其他要求,重試工作。
使用者提供的資料可在要求中做為查詢字串,或做為要求主體中的酬載來遞送至處理常式。如要瞭解如何插入使用者資料,請參閱建立工作一文。如果要求包含資料,處理常式必須知道資料是如何插入要求。從要求擷取資料的確切程式碼,取決於您使用的特定網頁架構。
如要測試工作處理常式,請以系統管理員身分登入,並使用瀏覽器造訪處理常式的網址。
讀取要求標頭
發送工作的 HTTP 要求有 App Engine 所設定的特殊標頭,這些標頭含有您的處理常式可使用的工作專屬資訊。
如果外部使用者對您應用程式發出的要求中出現這些標頭,則系統會去除並更換這些標頭。但如果要求來自於已登入應用程式的系統管理員,則屬唯一例外情況,系統允許管理員設定標頭以進行測試。另一方面,當您的應用程式在開發伺服器中執行時,系統也不會移除標頭。
來自工作佇列的要求一律會包含下列標頭:
| 標頭 | 說明 |
|---|---|
X-Appengine-QueueName |
佇列名稱 (可能是「default」,代表預設的發送佇列)。 |
X-Appengine-TaskName |
工作名稱。如未指定名稱,則為系統產生的專屬 ID。 |
X-Appengine-TaskRetryCount |
這個工作的已重試次數。若為第一次嘗試,此值為 0。這個數字會將工作因欠缺可用執行個體,所以從未達到執行階段而失敗的次數計算在內。 |
X-Appengine-TaskExecutionCount |
這個工作之前在執行階段失敗的次數。這個數字不包括因欠缺可用執行個體而失敗的次數。 |
X-Appengine-TaskETA |
指定的工作目標執行時間 (從 1970 年 1 月 1 算起,單位為秒)。 |
如果要求處理常式找到上述任何標頭,即可信任該要求為工作佇列要求。
此外,來自工作佇列的要求可能包含下列標頭:
| 標頭 | 說明 |
|---|---|
X-Appengine-TaskPreviousResponse |
上次重試的 HTTP 回應代碼。 |
X-Appengine-TaskRetryReason |
重試工作的原因。 |
X-Appengine-FailFast |
表示如果沒有可用的現有執行個體,則工作執行會立即失敗。 |
保護工作處理常式網址
如果工作會執行敏感的操作 (如修改資料),您可以保護處理常式網址,以防止惡意的外部使用者直接呼叫。您可以僅讓 App Engine 系統管理員擁有存取權,以防止使用者存取工作網址。工作要求本身由 App Engine 發出,所以可一律指定限定網址。
如要限制網址,請在 app.yaml 檔案的處理常式設定中,新增 login: admin 元素。
例如:
handlers:
- url: /your-task
script: worker.app
login: admin
後續步驟
- 瞭解如何刪除工作。