設定到期快訊

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

使用 TLS 期限快訊，讓系統在環境中的 TLS 憑證即將到期時傳送通知。

關於 TLS 憑證

TLS (傳輸層安全標準) 是一項標準安全性技術，可在網路伺服器與網路用戶端 (例如瀏覽器或應用程式) 之間建立加密連結。加密連結可確保在伺服器和用戶端之間傳輸的所有資料不會外洩。

TLS 憑證是一種數位檔案，可用來識別 TLS 交易中的實體。Edge 會使用傳輸層安全標準 (TLS) 憑證為下列項目設定傳輸層安全標準 (TLS)：

TLS 憑證含有到期日，如果 TLS 憑證過期，TLS 連線會失敗，直到您更新憑證為止。這表示在您更新憑證之前，傳送至 API 的所有要求都會失敗。

關於到期快訊

您不必等待憑證過期，也使用過期快訊，在環境中有任何 TLS 憑證即將到期時，系統會發出通知，您無須等待憑證過期和傳送至 API 的要求。觸發快訊後，您可以更新憑證，以免客戶看見任何服務中斷。

設定快訊時，請不要指定個別憑證，而是特定環境。 如果任何部署的憑證已排定在指定時間範圍內過期，就會觸發快訊。

您可以設定觸發到期時間快訊：

  • 憑證到期前 1 天
  • 憑證到期前 14 天
  • 憑證到期前 30 天
如要進一步瞭解快訊，請參閱「設定快訊和通知」。

新增到期快訊和通知

如何新增到期快訊和通知：
  1. 在 Edge UI 中，依序點選「Analyze」(分析) >「Alert Rules」(快訊規則)。
  2. 按一下「+快訊」。
  3. 輸入下列與快訊相關的一般資訊：
    欄位 說明
    快訊名稱 快訊名稱。請使用能夠貼切描述觸發條件且對您有意義的名稱。名稱長度不得超過 128 個字元。
    說明 快訊的說明。
    快訊類型 選取「TLS 到期時間」。詳情請參閱「關於快訊類型」一文。
    環境 從下拉式清單中選取環境。
    狀態 切換啟用或停用快訊。
  4. 定義觸發快訊的條件的門檻和維度。
    條件欄位 說明
    門檻

    設定即將到期憑證的時間範圍。你可以選擇在憑證即將到期時發出快訊：

    • 1 天
    • 14 天
    • 30 天
    維度 維度的值固定為「任何傳輸層安全標準 (TLS) 憑證」的值，與環境中任何傳輸層安全標準 (TLS) 憑證對應。
  5. 按一下「+ 通知」即可新增快訊通知。
    通知詳細資訊 說明
    頻道 選取您要使用的通知管道，並指定目的地：Email、Slack、PagerDuty 或 Webhook。
    目的地 根據選取的管道類型指定目的地：
    • 電子郵件 - 電子郵件地址，例如 joe@company.com
    • Slack - Slack 頻道網址，例如 https://hooks.slack.com/services/T00000000/B00000000/XXXXX
    • PagerDuty - PagerDuty 程式碼，例如 abcd1234efgh56789
    • Webhook - Webhook 網址，例如 https://apigee.com/test-webhook

      注意：每則通知只能指定一個目的地。如要為同一管道類型指定多個目的地，請新增其他通知。
  6. 如要新增其他通知，請重複上一個步驟。
  7. 如果您已經新增通知，請設定下列欄位：
    欄位 說明
    教戰手冊 (選填) 任意形式的文字欄位，針對觸發快訊時的建議動作提供簡短說明。您也可以指定內部維基或社群網頁的連結，以便參考最佳做法。這個欄位中的資訊會包含在通知中。這個欄位的內容不得超過 1500 個字元。
    節流 傳送通知的頻率。從下拉式清單中選取所需的值。
  8. 按一下「儲存」。

在「事件」資訊主頁查看快訊

當 Edge 偵測到快訊條件時，會自動將條件記錄到 Edge UI 的「Events」(事件) 資訊主頁。「事件」資訊主頁中顯示的事件清單會列出所有快訊 (包括固定和憑證)。

如何查看快訊：

  1. 在 Edge UI 中，依序按一下「分析」>「事件」。新的「活動」資訊主頁畫面會顯示：

  2. 依下列條件篩選「事件」資訊主頁：

    • 環境
    • 區域
    • 時間範圍
  3. 在事件資訊主頁中選取資料列，即可顯示含有即將到期憑證的 KeyStore，以便進一步調查快訊內容。您可以透過 KeyStore 頁面上傳新憑證並刪除即將到期的憑證。

使用期限快訊的 Alert API

用於建立及管理到期快訊的 API，與您用於固定快訊的 API 相同。下列快訊 API 運作方式與固定快訊和到期快訊相同：

不過，部分 API 具有額外屬性來支援異常快訊，包括：

建立或更新到期快訊

使用與目前處理固定快訊相同的 API 建立或更新到期快訊。用於建立或更新到期時間快訊的 API 呼叫主體與固定快訊使用的相同，但有下列異動：

  • 您必須加入下列新資源，才能指定快訊是即將到期的快訊：

    "alertType": "cert"
"alertSubType": "certfixed"

    這些屬性的預設值如下：

    "alertType": "runtime"
"alertSubType": "fixed"

  • 在 conditions 陣列中：

    • metrics 屬性僅採用 expiration 的值。
    • 使用 gracePeriodSeconds 屬性指定憑證的到期時間範圍 (以秒為單位)，上限為 30 天。
    • 不支援 threshold、durationSeconds 及 comparator 屬性。
  • 在 conditions 陣列的 dimensions 元素中：
    • 您必須將 certificate 屬性的值設為 ANY。
    • 您必須將 proxy 屬性的值設為 ALL。
    • 不支援 statusCode、developerApp、collection、faultCodeCategory、faultCodeSubCategory、faultCodeName 屬性。
  • 到期快訊不支援 reportEnabled 屬性。

下列 API 呼叫範例會建立到期快訊，如果實際執行環境中發生任何問題，就會於未來 30 天內到期。觸發快訊時，系統會將通知傳送到指定的電子郵件地址：

curl 'https://apimonitoring.enterprise.apigee.com/alerts' \
 -X POST \
 -H 'Accept: application/json, text/plain, */*' -H "Content-Type: application/json" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -d '{
  "organization":"myorg",
  "name":"My Cert Expiry Alert",
  "description":"My Cert Expiry Alert",
  "environment":"prod",
  "enabled":true,
  "alertType": "cert",
  "alertSubType": "certfixed",
  "conditions":[
  {
    "description":"My Cert Expiry Alert",
    "dimensions":{
      "org":"myorg",
      "env":"prod",
      "proxy":"ALL",
      "certificate": "ANY"
    },
    "metric":"expiration",
    "gracePeriodSeconds": 2592000
  }],
  "notifications":[{
    "channel":"email",
    "destination":"ops@acme.com"
  }],
  "playbook":"http://acme.com/pb.html",
  "throttleIntervalSeconds":3600,
  "reportEnabled":false
}'

按照「取得 OAuth 2.0 存取權杖」一節的說明，將 $ACCESS_TOKEN 設為 OAuth 2.0 存取權杖。如要瞭解本範例中使用的 cURL 選項，請參閱「使用 cURL」一文。

取得到期快訊

根據預設，Get Alerts API 會傳回所有已定義快訊的相關資訊 (包括固定快訊和到期時間)。這個 API 現在會採用查詢參數，以便篩選結果：

  • enabled - 如果 true 指定只傳回已啟用的快訊，預設值為 false。
  • alertType：指定要傳回的快訊類型。允許的值為 runtime、預設值和 cert。
  • alertSubType：指定要傳回的快訊子類型。未設定預設值，表示會傳回所有快訊子類型。指定 certfixed 即可傳回到期快訊。

舉例來說，使用下列 API 呼叫，即可只傳回 myorg 機構的快訊：

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&enabled=true'

下列呼叫只會傳回已啟用和已停用的到期快訊：

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
'https://apimonitoring.enterprise.apigee.com/alerts?org=myorg&alertType=cert&alertSubType=certfixed'

按照「取得 OAuth 2.0 存取權杖」一節的說明，將 $ACCESS_TOKEN 設為 OAuth 2.0 存取權杖。如要瞭解本範例中使用的 cURL 選項，請參閱「使用 cURL」一文。