Administra y descubre extremos

Para administrar de manera eficaz tu flota de agentes, debes mantener actualizada tu red de extremos. En este documento, se detalla cómo descubrir los extremos disponibles, actualizar sus detalles de conexión o quitarlos cuando ya no se usan.

Antes de comenzar

Antes de que puedas administrar los extremos, regístralos en Agent Registry. También necesitas el ID del proyecto para realizar estas tareas.

Para usar los comandos de gcloud CLI en este documento, asegúrate de haber configurado tu Google Cloud CLI Cloud.

Roles obligatorios

Para obtener los permisos que necesitas para administrar los extremos en Agent Registry, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Descubre extremos

Para explorar las URLs de destino y las APIs de REST registradas en tu entorno, enumera los recursos de extremos disponibles.

Enumera todos los extremos

Enumera todos los extremos registrados en tu entorno:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

    En la página, se muestra una lista de todos los extremos registrados y sus detalles, como el nombre, la descripción y la ubicación.

  4. Para ver los detalles de conexión completos de un extremo, haz clic en su nombre.

gcloud

Para enumerar todos los extremos en una ubicación específica, usa el comando endpoints list:

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

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro

Filtra los extremos registrados

Si tienes varios extremos, puedes filtrar la lista por los metadatos del extremo:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

    En la página, se muestra una lista de todos los extremos registrados y sus detalles, como el nombre, la descripción y la ubicación.

  4. Para filtrar por ubicación, haz clic en el menú Ubicación , selecciona las ubicaciones que deseas filtrar y haz clic en Aplicar.

    En la página, se muestra una lista filtrada de los extremos registrados para las condiciones seleccionadas.

gcloud

Filtra tu lista para que solo muestre los recursos que coinciden con metadatos específicos, usando la marca --filter:

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

Reemplaza FILTER_EXPRESSION por la expresión de filtro de los extremos que deseas filtrar. Por ejemplo, para filtrar por nombre visible, usa displayName='DISPLAY_NAME'.

Terraform

Para recuperar un extremo registrado específico filtrando sus metadatos, configura la fuente de datos google_agent_registry_endpoint con el argumento filter:

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

Reemplaza lo siguiente:

  • REGION: La región del registro
  • DISPLAY_NAME: El nombre legible del extremo por el que se filtrará, por ejemplo, Example API Endpoint

Consulta los detalles de un extremo

Consulta los detalles de un extremo específico, incluidos sus detalles de conexión y vinculaciones de protocolo:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

    En la página, se muestra una lista de todos los extremos registrados y sus detalles, como el nombre, la descripción y la ubicación.

  4. Haz clic en el nombre del extremo que deseas ver.

    En la página Descripción general, se muestran el nombre, la descripción, la ubicación y los detalles de conexión del extremo, incluida la URL de destino y las vinculaciones de protocolo.

gcloud

Recupera metadatos detallados sobre un extremo específico, incluida su URL de interfaz completa y la vinculación de protocolo:

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

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro
  • ENDPOINT_NAME: El nombre de tu extremo, por ejemplo, my-external-api

Terraform

Para recuperar detalles sobre un extremo registrado específico con su ID, configura la fuente de datos 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
}

Reemplaza lo siguiente:

  • REGION: La región del registro
  • ENDPOINT_NAME: El identificador único de tu extremo, por ejemplo, my-external-api

Actualiza un extremo

Si cambia la URL subyacente de un extremo de destino externo, puedes actualizar los detalles de la interfaz del extremo.

Sigue estos pasos para actualizar un extremo:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

    En la página, se muestra una lista de todos los extremos registrados y sus detalles, como el nombre, la descripción y la ubicación.

  4. Haz clic en el nombre del extremo que deseas actualizar.

    En la página Descripción general, se muestran el nombre, la descripción, la ubicación y los detalles de conexión del extremo, incluida la URL de destino y las vinculaciones de protocolo.

  5. Haz clic en Editar.

  6. En el panel Editar servicio , ingresa la información actualizada del extremo, como el nombre visible, la descripción y la URL de destino. Puedes probar la conexión al extremo desde este panel.

  7. Haz clic en Guardar.

gcloud

Para la API de Agent Registry, los recursos Endpoint se usan para el descubrimiento. Por lo tanto, debes actualizar el recurso Service registrado directamente.

Usa la marca --interfaces para especificar la nueva URL de destino:

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

Reemplaza lo siguiente:

  • ENDPOINT_NAME: El nombre de tu extremo, por ejemplo, my-external-api
  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro
  • ENDPOINT_URL: La nueva URL de destino, por ejemplo, https://new-api.example.com/v1/data
  • PROTOCOL: La vinculación de protocolo para la interfaz Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Terraform

Para actualizar una URL de extremo o una vinculación de protocolo con Terraform, modifica el bloque interfaces de tu recurso google_agent_registry_service existente en tu configuración y, luego, ejecuta 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"
  }
}

Reemplaza lo siguiente:

  • REGION: La región del registro
  • ENDPOINT_NAME: El nombre de tu extremo
  • DISPLAY_NAME: El nombre legible del extremo
  • ENDPOINT_URL: La nueva URL de destino, por ejemplo, https://new-api.example.com/v1/data
  • PROTOCOL: La vinculación de protocolo para la interfaz Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Quita un extremo

Para quitar un extremo del registro, debes borrar su recurso Service subyacente. Esta acción quita de inmediato el extremo de los resultados de la búsqueda de descubrimiento.

Sigue estos pasos para quitar un extremo de tu registro:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

    En la página, se muestra una lista de todos los extremos registrados y sus detalles, como el nombre, la descripción y la ubicación.

  4. Haz clic en el nombre del extremo que deseas quitar.

    En la página Descripción general, se muestran el nombre, la descripción, la ubicación y los detalles de conexión del extremo, incluida la URL de destino y las vinculaciones de protocolo.

  5. Haz clic en Borrar.

  6. En la ventana Borrar extremo, ingresa DELETE para confirmar la acción.

  7. Haz clic en Borrar.

gcloud 

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

Terraform

Quita el recurso google_agent_registry_service que representa el extremo de tu configuración de Terraform y, luego, ejecuta terraform apply.