Gestire e scoprire gli endpoint

La gestione efficace della flotta di agenti richiede che la rete di endpoint sia accurata. Questo documento descrive in dettaglio come scoprire gli endpoint disponibili, aggiornarne i dettagli di connessione o rimuoverli quando non sono più in uso.

Prima di iniziare

Prima di poter gestire gli endpoint, devi registrarli in Agent Registry. Per eseguire queste attività, devi anche avere l'ID progetto.

Per utilizzare i comandi gcloud CLI in questo documento, assicurati di aver configurato l'ambiente Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire gli endpoint in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Scopri endpoint

Per sfogliare gli URL di destinazione e le API REST registrate nel tuo ambiente, elenca le risorse endpoint disponibili.

Elenca tutti gli endpoint

Elenca tutti gli endpoint registrati nel tuo ambiente:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

    La pagina mostra un elenco di tutti gli endpoint registrati e i relativi dettagli, come nome, descrizione e località.

  4. Per visualizzare i dettagli completi della connessione di un endpoint, fai clic sul nome dell'endpoint.

gcloud

Per elencare tutti gli endpoint in una località specifica, utilizza il comando endpoints list:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.

Filtra gli endpoint registrati

Se hai più endpoint, puoi filtrare l'elenco in base ai metadati dell'endpoint:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

    La pagina mostra un elenco di tutti gli endpoint registrati e i relativi dettagli, come nome, descrizione e località.

  4. Per filtrare in base alla località, fai clic sul menu Località , seleziona le località che vuoi filtrare e fai clic su Applica.

    La pagina mostra un elenco filtrato degli endpoint registrati per le condizioni selezionate.

gcloud

Filtra l'elenco in modo da restituire solo le risorse che corrispondono a metadati specifici utilizzando il flag --filter:

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

Sostituisci FILTER_EXPRESSION con l'espressione di filtro per gli endpoint che vuoi filtrare. Ad esempio, per filtrare in base al nome visualizzato, utilizza displayName='DISPLAY_NAME'.

Terraform

Per recuperare un endpoint registrato specifico filtrando in base ai relativi metadati, configura l'origine dati google_agent_registry_endpoint con l'argomento filter:

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

Sostituisci quanto segue:

  • REGION: la regione del registro.
  • DISPLAY_NAME: il nome leggibile dell'endpoint in base al quale filtrare, ad esempio Example API Endpoint.

Visualizza i dettagli di un endpoint

Visualizza i dettagli di un endpoint specifico, inclusi i dettagli di connessione e i binding di protocollo:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

    La pagina mostra un elenco di tutti gli endpoint registrati e i relativi dettagli, come nome, descrizione e località.

  4. Fai clic sul nome dell'endpoint che vuoi visualizzare.

    La pagina Panoramica mostra il nome, la descrizione, la località e i dettagli di connessione dell'endpoint, inclusi l'URL di destinazione e i binding di protocollo.

gcloud

Recupera i metadati dettagliati di un endpoint specifico, inclusi l'URL completo dell'interfaccia e il binding di protocollo:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • ENDPOINT_NAME: il nome dell'endpoint, ad esempio my-external-api.

Terraform

Per recuperare i dettagli di un endpoint registrato specifico utilizzando il relativo ID, configura l'origine dati 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
}

Sostituisci quanto segue:

  • REGION: la regione del registro.
  • ENDPOINT_NAME: l'identificatore univoco dell'endpoint, ad esempio my-external-api.

Aggiorna un endpoint

Se l'URL sottostante di un endpoint di destinazione esterno cambia, puoi aggiornare i dettagli dell'interfaccia dell'endpoint.

Per aggiornare un endpoint:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

    La pagina mostra un elenco di tutti gli endpoint registrati e i relativi dettagli, come nome, descrizione e località.

  4. Fai clic sul nome dell'endpoint che vuoi aggiornare.

    La pagina Panoramica mostra il nome, la descrizione, la località e i dettagli di connessione dell'endpoint, inclusi l'URL di destinazione e i binding di protocollo.

  5. Fai clic su Modifica.

  6. Nel riquadro Modifica servizio , inserisci le informazioni aggiornate per l'endpoint, come il nome visualizzato, la descrizione e l'URL di destinazione. Da questo riquadro puoi testare la connessione all'endpoint.

  7. Fai clic su Salva.

gcloud

Per l'API Agent Registry, le risorse Endpoint vengono utilizzate per la rilevabilità. Pertanto, devi aggiornare direttamente la risorsa Service registrata.

Utilizza il flag --interfaces per specificare il nuovo URL di destinazione:

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

Sostituisci quanto segue:

  • ENDPOINT_NAME: il nome dell'endpoint, ad esempio my-external-api.
  • PROJECT_ID: l'ID progetto.
  • REGION: la regione del registro.
  • ENDPOINT_URL: il nuovo URL di destinazione, ad esempio https://new-api.example.com/v1/data.
  • PROTOCOL: il binding di protocollo per l'interfaccia. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Terraform

Per aggiornare un URL endpoint o un binding di protocollo utilizzando Terraform, modifica il blocco interfaces della risorsa google_agent_registry_service esistente nella configurazione, quindi esegui 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"
  }
}

Sostituisci quanto segue:

  • REGION: la regione del registro.
  • ENDPOINT_NAME: il nome dell'endpoint.
  • DISPLAY_NAME: il nome leggibile dell'endpoint.
  • ENDPOINT_URL: il nuovo URL di destinazione, ad esempio https://new-api.example.com/v1/data.
  • PROTOCOL: il binding di protocollo per l'interfaccia. I valori validi sono HTTP_JSON, GRPC o JSONRPC.

Rimuovi un endpoint

Per rimuovere un endpoint dal registro, devi eliminare la risorsa Service sottostante. Questa azione rimuove immediatamente l'endpoint dai risultati di ricerca di rilevabilità.

Per rimuovere un endpoint dal registro:

Console

  1. Nella Google Cloud console, vai ad Agent Registry:

    Vai ad Agent Registry

  2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

  3. Seleziona la scheda Endpoint.

    La pagina mostra un elenco di tutti gli endpoint registrati e i relativi dettagli, come nome, descrizione e località.

  4. Fai clic sul nome dell'endpoint che vuoi rimuovere.

    La pagina Panoramica mostra il nome, la descrizione, la località e i dettagli di connessione dell'endpoint, inclusi l'URL di destinazione e i binding di protocollo.

  5. Fai clic su Elimina.

  6. Nella finestra Elimina endpoint, inserisci DELETE per confermare l'azione.

  7. Fai clic su Elimina.

gcloud 

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

Terraform

Rimuovi la risorsa google_agent_registry_service che rappresenta l'endpoint dalla configurazione di Terraform, quindi esegui terraform apply.