Shadow API Discovery 總覽

總覽

Shadow API Discovery 會在現有雲端基礎架構中找出 Shadow API (也稱為未記錄的 API)。Shadow API 可能未受保護、監控及維護，因此可能對系統造成安全風險。Shadow API Discovery 是 Apigee API Observation 的一部分。

您可以設定及執行工作，觀察個別專案中的 API 活動。 Google Cloud 在集中式 Apigee API 中心執行個體中，您可以附加這些專案，查看這些工作的結果，並自動與 API 中心記錄的「已知」API 進行比較。如要瞭解如何在 Apigee API 中心使用 Shadow API Discovery，請參閱「API 中心的 API 觀測功能」。

如要瞭解 Shadow API Discovery 的資料落地相容性，請參閱「 資料落地相容性」。

啟用 Shadow API Discovery

Shadow API Discovery 是 Advanced API Security 外掛程式的一部分，適用於 Google Cloud 已佈建或未佈建 Apigee 的專案。

如果您的 Google Cloud 專案已佈建 Apigee：

如果您的 Google Cloud 專案未佈建 Apigee，請聯絡 Apigee 銷售團隊，將 Shadow API Discovery 新增至專案。

從 Apigee 啟用 Shadow API Discovery

本節中設定及查看 API 觀測結果的操作說明，是以 Cloud 控制台的 Apigee UI 為準。您也可以使用 Apigee Management (APIM) API 管理 Shadow API Discovery。請參閱「Shadow API Discovery 管理 API」。

如要使用這項功能，必須啟用外掛程式。如果您是訂閱方案客戶，可以為機構啟用外掛程式。詳情請參閱「 為訂閱機構管理 Advanced API Security」。如果您是隨用隨付方案客戶，可以在符合資格的環境中啟用外掛程式。詳情請參閱「 管理 Advanced API Security 外掛程式」。

從 API 中心啟用 Shadow API Discovery

如要從 API 中心啟用 Shadow API Discovery，請按照「在 API 中心設定 API 觀察功能」一文中的操作說明進行。

Shadow API Discovery 的必要角色和權限

下表列出執行 Shadow API Discovery 相關工作時所需的角色。

工作 必要角色
啟用或停用 Advanced API Security Apigee 機構管理員 (roles/apigee.admin)
建立觀測來源和工作 API Management 管理員 (roles/apim.admin)
查看觀察項目 API Management 檢視者 (roles/apim.viewer)

在 Apigee UI 中存取 Shadow API Discovery

本節說明如何在 Apigee 使用者介面中存取 Shadow API Discovery。

如要在 Apigee 使用者介面存取 Shadow API Discovery，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往「API Observation」(API 觀察) >「Shadow API」(影子 API) 頁面。

    前往 Shadow API

  2. 主要頁面會顯示所有已產生的 API 觀測結果。選取「API Observations」(API 觀測) 和「Observation Jobs」(觀測工作) 分頁標籤，即可在查看結果和建立觀測工作之間切換。

建立觀測工作

觀測工作會提供 Shadow API Discovery 尋找隱藏 API 時所需的指示。請按照下列步驟建立觀察作業。請注意，建立觀察工作時，須遵守相關行為和限制。

  1. 選取「觀測工作」分頁，然後按一下「建立觀測工作」。
  2. 選取一或多個觀測來源，或按一下「觀測來源」清單底部的「建立觀測來源」，視需要建立新的來源位置。請注意，建立觀察來源的程序可能需要幾分鐘。

    觀察來源包括：
    來源名稱：您指定的來源識別名稱。
    位置：要觀察的位置。 納入更多來源區域，即可更全面地查看基礎架構中的 API。請參閱「最佳做法」。一個地點只能建立一個觀測來源。
    網路和子網路：虛擬私有雲網路和子網路。網路和子網路必須與觀察來源位於相同專案。子網路也必須與觀測來源位置位於相同區域。
  3. 建立觀測工作。提供觀察工作名稱，每個地點的名稱不得重複。選取位置，指定資料彙整和處理作業的發生位置。我們會在這個區域處理及存取來源區域收集到的所有資料，這符合 Google 的資料落地政策。建立新的觀察工作可能需要幾分鐘才能完成。
  4. 啟用觀測工作 (選用)。建立工作時，您可以啟用工作，這樣工作就會立即開始監控。如果沒有立即啟用工作，之後可以從觀測工作清單啟用觀測工作。

啟用、停用及刪除觀測工作

如要變更現有觀察作業的啟用 (有效) 狀態，請在「觀察作業」頁面中，選取該作業所在列的「動作」選單中的「啟用」或「停用」。

如要刪除現有觀測工作，請從該工作的「動作」選單中選取「刪除」。刪除工作也會移除與該工作相關的觀察結果，因此如要保留結果，但停止繼續執行工作，請停用工作，而非刪除。無法刪除有效工作，如要刪除，請先停用有效工作。

查看 API 觀測結果

如要查看已啟用觀測工作的 API 觀測項目，請選擇「API Observations」(API 觀測項目) 分頁標籤，然後從清單中選取「Observation job」(觀測工作)。

「API 觀測」頁面

觀察事項清單會顯示下列值：

  • 主機名稱：API 主機名稱。按一下主機名稱，即可查看觀測詳細資料。
  • API 作業：觀察到的 API 作業數量 (例如 GET 或 PUT 要求)。
  • 伺服器 IP：代管已探索 API 的伺服器 IP。
  • 來源位置：觀察到流量的來源位置。
  • 上次偵測到事件的時間 (世界標準時間)：系統偵測到最近一次 API 要求的日期和時間。
  • 標籤：您或其他使用者為這項觀察結果建立的標籤清單。詳情請參閱「使用標記」。
  • 動作：可對每項觀察結果執行的其他動作。

查看觀察結果詳細資料

按一下觀察清單中的主機名稱後，系統會顯示觀察詳細資料頁面。

Shadow API Discovery 觀測工作詳細資料

這個頁面包含下列觀察結果資訊。

  • 頁面頂端的摘要方塊會顯示：
    • API 觀測項目 ID：這是 Apigee 專屬的 ID。
    • API 作業：請參閱「查看 API 觀測結果」一節，瞭解這個欄位的說明。
    • 建立時間 (世界標準時間)：觀測工作的建立日期和時間。
    • 標記： 使用標記整理觀察作業結果。
    • 上次偵測到事件的時間：如需這個欄位的說明，請參閱「查看 API 觀測結果」。
  • 這項探索到的 API 中偵測到的特定 API 作業表格。系統會顯示每項要求的下列資訊：
    • 路徑：要求路徑。
    • 方法：要求方法 (例如 GET、PUT 等)。
    • 計數：使用該方法對該路徑提出的要求數量。
    • 交易要求：來自流量資料的要求內容。包括這項 API 作業的要求標頭和相應的交易計數。
    • 交易回應標頭：來自流量資料的回應標頭。包括此 API 作業的回應標頭和對應的交易計數。
    • 交易回應代碼：這個 API 作業的回應代碼，以及具有該代碼的回應數量。
    • 首次發現 (UTC)：系統首次觀察到對這項 API 作業的要求的日期和時間。
    • 上次出現時間 (世界標準時間)：最近一次觀察到對這個 API 作業提出要求的日期和時間。

使用標記

標記可讓您將觀察結果分類。標記是中繼資料，僅供追蹤用途，不會變更觀察結果中的任何內容，也不會觸發任何動作。舉例來說，新增「需要注意」標記不會產生任何通知或快訊。新的觀察結果沒有標記。

標記具有下列特性：

  • 您可以為多個觀察結果加上相同標籤。
  • 標記名稱可包含大小寫字元、數字和特殊字元，包括空格。
  • 建立標記後，名稱就無法變更；如要重新命名，請移除並重新建立標記。
  • 從所有觀察結果中移除標記，即可從系統中刪除標記。

您可以在觀察清單或觀察詳細資料頁面管理標記。

如要從 API 觀測結果清單管理標記，請按照下列步驟操作：

  • 在觀察事項清單的「標記」欄中查看現有標記。
  • 如要管理單一結果的標記，請在該結果的資料列中，選取「動作」選單中的「管理標記」。
  • 如要同時管理一或多個結果的標籤，請從清單中選取多個結果，然後在清單頂端點選「管理標籤」。

如要從「API 觀測工作詳細資料」管理標記，請按照下列步驟操作：

  • 在「代碼」部分查看現有代碼。
  • 如要新增或管理標記，請選擇頁面頂端的「管理標記」。

在「管理標記」側邊面板中，選取現有標記或新增標記，即可新增標記。 如要移除標記，請取消選取。按一下「儲存」即可儲存新代碼。

從 API 中心存取 Shadow API Discovery

如要瞭解如何從 API 中心存取 Shadow API Discovery，請參閱「在 API 中心管理 API 觀察功能」。

最佳做法

使用 Shadow API Discovery 時，建議採取下列做法：

  • 請遵守貴機構的資料落地規則，確保符合所有適用的法規和法律。
  • 盡可能從多個來源區域匯總資料，以取得最佳的跨區域關聯性。在觀測工作中納入更多來源區域，可更全面地瞭解基礎架構中的 API。

行為和限制

本節列出 Shadow API Discovery 適用的行為和限制：

  • 使用 Shadow API Discovery 不保證可觀測 100% 的流量，或找出所有 Shadow API。
  • Shadow API Discovery 只會找出 Google Cloud 基礎架構中的 Shadow API。
  • 觀察工作和來源必須在設定虛擬私有雲網路和子網路的專案中設定。
  • 目前，Shadow API Discovery 僅支援外部和內部 應用程式負載平衡器。系統不支援網路負載平衡器。
  • Shadow API Discovery 會找出 HTTP 通訊協定 API，而非 gRPC。
  • 在負載平衡器上執行 API 觀測工作，不會對 API 流量造成任何延遲影響。
  • 警告：Shadow API Discovery 支援每個專案一個網路上的負載平衡器。如果您在有多個網路的專案中啟用 Shadow API Discovery，可能會發生異常行為。
  • 觀察專案中的負載平衡器必須有流量流經，才能偵測到 Shadow API。
  • 新啟用的觀察工作最多可能需要 30 分鐘才能偵測到流量，實際時間取決於流量大小。稀疏流量需要較長的觀察時間，結果才會出爐。
  • 每個區域最多只能有一個觀測來源，以及最多三個觀測工作。如需超過三項觀察作業，請與 Google Cloud 客戶服務團隊聯絡，討論使用案例。
  • 觀察工作可以建立、停用或刪除，但無法編輯。如要變更觀測工作，請刪除並重新建立。
  • 目前支援 API 觀測和 Shadow API 的區域如下：
    • australia-southeast1
    • europe-west2
    • europe-west9
    • us-central1
    • us-east1
    • us-west1