管理及探索端點

您可以透過代理程式註冊資料庫，探索、更新及移除已註冊的端點，確保代理程式將流量轉送至有效的目標網址。此外，您也能檢查專案中的可用端點、在基礎架構變更時更新連線詳細資料，以及移除不再使用的端點。

事前準備

  1. 設定 Agent Registry。

  2. 取得已啟用 Agent Registry 的管理專案專案 ID。

  3. 在 Agent Registry 中註冊端點。

  4. 如要使用本文件中的 Google Cloud CLI 指令，請設定 gcloud CLI 環境。

必要的角色

如要取得在 Agent Registry 管理端點所需的權限，請要求管理員在已啟用 Agent Registry 的管理專案中，授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

探索端點

如要瀏覽環境中註冊的目標網址和 REST API，請列出可用的 Endpoint 資源。

列出所有端點

列出環境中所有已註冊的端點：

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」：

    前往代理程式註冊頁面

  2. 在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。

  3. 選取「Endpoints」分頁標籤。

    這個頁面會列出所有已註冊的端點及其詳細資料，例如名稱、說明和位置。

  4. 如要查看端點的完整連線詳細資料，請按一下端點名稱。

gcloud

如要列出特定位置的所有端點，請執行 gcloud agent-registry endpoints list 指令：

gcloud agent-registry endpoints list \
    --project=PROJECT_ID \
    --location=REGION

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。

篩選已註冊的端點

如果您有多個端點，可以依端點的中繼資料篩選清單：

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」：

    前往代理程式註冊頁面

  2. 在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。

  3. 選取「Endpoints」分頁標籤。

    這個頁面會列出所有已註冊的端點及其詳細資料，例如名稱、說明和位置。

  4. 如要依位置篩選，請按一下「Location」(位置) 選單，選取要篩選的位置，然後按一下「Apply」(套用)。

    頁面會根據所選條件，顯示已註冊端點的篩選清單。

gcloud

將 --filter 旗標傳遞至 gcloud agent-registry endpoints list 指令，篩選清單，只傳回符合特定中繼資料的資源：

gcloud agent-registry endpoints list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。
  • FILTER_EXPRESSION：要篩選的端點篩選運算式。例如，如要依顯示名稱篩選，請使用 displayName='DISPLAY_NAME'。如要依全域專屬端點 ID (URN) 篩選，請使用 endpointId='urn:endpoint:ENDPOINT_URN'。

Terraform

如要依中繼資料篩選，擷取特定已註冊的端點，請使用 filter 引數設定 google_agent_registry_endpoint 資料來源：

data "google_agent_registry_endpoint" "filtered_endpoint" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

更改下列內容：

  • REGION：登錄檔區域。
  • DISPLAY_NAME：要篩選的端點人類可讀名稱，例如 Example API Endpoint。

查看端點詳細資料

查看特定端點的詳細資料，包括連線詳細資料和通訊協定繫結：

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」：

    前往代理程式註冊頁面

  2. 在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。

  3. 選取「Endpoints」分頁標籤。

    這個頁面會列出所有已註冊的端點及其詳細資料，例如名稱、說明和位置。

  4. 按一下要查看的端點名稱。

    「Overview」(總覽) 頁面會顯示端點的名稱、說明、位置和連線詳細資料，包括到達網頁網址和通訊協定繫結。

gcloud

執行 gcloud agent-registry endpoints describe 指令，擷取特定端點的詳細中繼資料，包括完整介面網址和通訊協定繫結：

gcloud agent-registry endpoints describe ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。
  • ENDPOINT_NAME：端點名稱，例如 my-external-api。

Terraform

如要使用 ID 擷取特定已註冊端點的詳細資料，請設定 google_agent_registry_endpoint 資料來源：

data "google_agent_registry_endpoint" "my_endpoint" {
  location    = "REGION"
  endpoint_id = "ENDPOINT_NAME"
}

output "endpoint_create_time" {
  description = "The timestamp when the endpoint was registered."
  value       = data.google_agent_registry_endpoint.my_endpoint.create_time
}

output "endpoint_update_time" {
  description = "The timestamp when the endpoint was last updated."
  value       = data.google_agent_registry_endpoint.my_endpoint.update_time
}

更改下列內容：

  • REGION：登錄檔區域。
  • ENDPOINT_NAME：端點的專屬 ID，例如 my-external-api。

更新端點

如果外部目標端點的基礎網址有所變更，您可以更新端點介面詳細資料。

在 Agent Registry 中，Endpoint 資源是唯讀的探索資源。因此，如要更新已註冊的端點，您必須直接更新其可寫入的 Service 資源。

請按照下列步驟更新端點：

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」：

    前往代理程式註冊頁面

  2. 在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。

  3. 選取「Endpoints」分頁標籤。

    這個頁面會列出所有已註冊的端點及其詳細資料，例如名稱、說明和位置。

  4. 按一下要更新的端點名稱。

    「Overview」(總覽) 頁面會顯示端點的名稱、說明、位置和連線詳細資料，包括到達網頁網址和通訊協定繫結。

  5. 按一下「Edit」(編輯)。

  6. 在「Edit service」(編輯服務) 面板中，輸入端點的更新資訊，例如顯示名稱、說明和到達網頁網址。您可以在這個面板測試與端點的連線。

  7. 按一下 [儲存]。

gcloud

執行 gcloud agent-registry services update 指令，並使用 --interfaces 旗標指定新的目標網址：

gcloud agent-registry services update ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

更改下列內容：

  • ENDPOINT_NAME：端點名稱，例如 my-external-api。
  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。
  • ENDPOINT_URL：新的目標網址，例如 https://new-api.example.com/v1/data。
  • PROTOCOL：介面的通訊協定繫結。有效值為 http-json、grpc 或 jsonrpc。

Terraform

如要使用 Terraform 更新端點網址或通訊協定繫結，請修改設定中現有 google_agent_registry_service 資源的 interfaces 區塊，然後執行 terraform apply：

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }

  endpoint_spec {
    type = "NO_SPEC"
  }
}

更改下列內容：

  • REGION：登錄檔區域。
  • ENDPOINT_NAME：端點名稱。
  • DISPLAY_NAME：端點的人類可讀名稱。
  • ENDPOINT_URL：新的目標網址，例如 https://new-api.example.com/v1/data。
  • PROTOCOL：介面的通訊協定繫結。有效值為 HTTP_JSON、GRPC 或 JSONRPC。

移除端點

如要從登錄檔中移除端點，您必須刪除其 Service 資源。這項操作會立即從探索搜尋結果中移除端點。

請按照下列步驟，從登錄檔中移除端點：

控制台

  1. 前往 Google Cloud 控制台的「Agent Registry」：

    前往代理程式註冊頁面

  2. 在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。

  3. 選取「Endpoints」分頁標籤。

    這個頁面會列出所有已註冊的端點及其詳細資料，例如名稱、說明和位置。

  4. 按一下要移除的端點名稱。

    「Overview」(總覽) 頁面會顯示端點的名稱、說明、位置和連線詳細資料，包括到達網頁網址和通訊協定繫結。

  5. 按一下「刪除」圖示 。

  6. 在「Delete endpoint」(刪除端點) 視窗中，輸入 DELETE 來確認操作。

  7. 點選「刪除」。

gcloud

請執行 gcloud agent-registry services delete 指令。

gcloud agent-registry services delete ENDPOINT_NAME \
    --project=PROJECT_ID \
    --location=REGION

更改下列內容：

  • ENDPOINT_NAME：要移除的端點名稱，例如 my-external-api。
  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。

Terraform

從 Terraform 設定中移除代表端點的 google_agent_registry_service 資源，然後執行 terraform apply。