使用 Cron 安排工作時程 (適用於 Java 8)

透過 App Engine Cron 服務,您可以定期設定排程工作;這些排程工作會依照您定義的時間或規律間隔執行作業,通常稱為「Cron 工作」。App Engine Cron Service 將自動觸發 Cron 工作。例如,您可以使用 Cron 工作每天傳送一次電子郵件報告,或是每 10 分鐘更新某些快取資料,也可以每小時重新整理一次摘要資訊。

Cron 工作會按照既定排程對網址發出 HTTP GET 要求。該網址的處理常式會在收到呼叫時執行邏輯。Cron 工作要求和推送工作佇列遵循一樣的限制。

事前準備

如要部署或更新排程,您的帳戶需要下列其中一種 IAM 角色:

  • 擁有者
  • 編輯者

您可以在 Google Cloud Platform 主控台中的「IAM」頁面中設定權限。

建立 Cron 工作

  1. 在應用程式的 WEB-INF/ 目錄中建立 cron.xml 檔案 (以及 appengine-web.xml)。
  2. 在檔案中新增一或多個 <cron> 項目,然後定義工作的必要元素 (包括不可或缺的 <url><schedule> 元素)。

    以下範例會建立一個每天執行的基本 Cron 工作:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries>
      <cron>
        <url>/tasks/summary</url>
        <target>beta</target>
        <description>daily summary job</description>
        <schedule>every 24 hours</schedule>
      </cron>
    </cronentries>
    

    目標規格是服務/版本的名稱,填或不填均可。如果指定目標,就會在應用程式的主機名稱後加上目標,將工作轉送到該服務/版本。如不指定目標,則這項工作會在已經完成流量設定的 default 服務版本中執行。

  3. 建立 Cron 工作網址的處理常式。此處理常式應執行您要排程的任何工作,並回應代表成功的 HTTP 狀態碼,這個狀態碼介於 200 和 299 (含首尾) 之間。可能會傳回其他狀態碼,也可以使用這些狀態碼重試 Cron 工作

處理常式可以像應用程式中的 Servlet 一樣簡單。在 web.xml 中對應的 Servlet 網址應與 Cron 工作網址相同。進一步瞭解 cron.xml 語法和選項

在開發伺服器中測試 Cron 工作

本機開發伺服器不會自動執行您的 Cron 工作。您可以直接對 Cron 工作的網址發出要求以測試功能。您可以使用 curl 或類似的工具,以本機 Cron 或排程工作的介面觸發工作網址。

重試失敗的 Cron 工作

如果 Cron 工作要求處理常式傳回的 HTTP 狀態碼不在 200–299 (含首尾) 範圍內,則 App Engine 會將工作視為失敗。根據預設,除非傳回的狀態代碼是 503,否則一律不重試失敗的工作,若傳回 503,則會每分鐘重試一次,直到工作成功或傳回介於 200-299 這個範圍內的狀態代碼。

如要設定重試失敗的工作:

  1. cron.xml 檔案中加入 retry-parameters 區塊。
  2. retry-parameters 區塊中選擇並設定retry-parameters

    例如,以下的 cron.xml 範例檔包含一項 Cron 工作,這項工作的設定是最多重試五次 (預設值),開始輪詢時間是 2.5 秒,每次加倍。

    <cronentries>
      <cron>
        <url>/retry</url>
        <description>Retry on jsdk</description>
        <schedule>every 10 minutes</schedule>
        <retry-parameters>
          <min-backoff-seconds>2.5</min-backoff-seconds>
          <max-doublings>5</max-doublings>
        </retry-parameters>
      </cron>
    </cronentries>
    

深入瞭解 Cron 重試選項。

部署 Cron 工作

選項 1:上傳整個應用程式

如要上傳整個應用程式,並使用 cron.xml 檔案中的項目更新 Cron 服務,請執行以下指令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
選項 2:僅上傳您的 Cron 更新內容

如要僅更新 Cron 設定而不上傳應用程式的其餘部分,請執行以下指令:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

刪除所有 Cron 工作

如要刪除所有 Cron 工作,請按照下列指示操作:

  1. 按照下列方式修改 cron.xml 檔案中的內容:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    
  2. cron.xml 檔案部署至 App Engine。

設定 Cron 網址安全性

如要避免使用者存取排程工作所使用的網址,可以限制只有管理員帳戶才有存取權。已排程工作可以存取只限管理員存取的網址。您可以在安全與驗證瞭解如何限制網址。下列使用於 web.xml 的範例會將以 /cron/ 開頭的所有內容限制為僅限管理員存取:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>cron</web-resource-name>
        <url-pattern>/cron/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

如要進一步瞭解 web.xml 格式,請參閱部署作業描述元的說明文件。

如要測試 Cron 工作,請以管理員身分登入,並透過瀏覽器造訪處理常式的網址。

來自 Cron 服務的要求也會包含 HTTP 標頭:

X-Appengine-Cron: true

X-Appengine-Cron 標頭是由 Google App Engine 在內部設定的。若您的要求處理常式找到這個標頭,處理常式即可信任這項要求是 Cron 要求。若外部使用者對應用程式發出的要求出現此標頭,將會移除此標頭,除非這是應用程式登入管理員發出的要求,因為只有登入管理員能夠針對測試目的設定標頭。

Google App Engine 會從 IP 位址 0.1.0.1 發出 Cron 要求。

呼叫 Google Cloud Endpoints

您無法在 Cron 工作的 url 欄位中指定 Google Cloud Endpoint。如果要讓 Cron 工作呼叫 Google Cloud 端點,請針對應用程式中由處理常式提供的目標發出要求,並使用處理常式程式碼呼叫端點類別及方法。

在 GCP 主控台中查看 Cron 工作

您可以在 GCP 主控台的「Cron jobs」(Cron 工作) 頁面查看 Cron 工作的排程。

您也可以在記錄頁面查看之前新增或移除 Cron 工作的時間。

瞭解詳情

如需進一步瞭解定義 Cron 工作,請參閱 cron.xml 參考資料

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 適用的 App Engine 標準環境