API de Dynatrace SaaS: el mapa completo de las API y de los esquemas de Settings 2.0

API de Dynatrace SaaS: Environment API v2, Settings 2.0, API de plataforma y OAuth en una tabla, esquemas útiles, ejemplos con curl y trampas de paginación
API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

Tienes que automatizar una configuración, extraer métricas para un informe de SLO o conectar una herramienta interna a Dynatrace. Muy pronto vuelve la misma pregunta: ¿qué API llamar, con qué URL y con qué token? La API de Dynatrace SaaS no es un bloque único, sino varias familias que no comparten ni la misma dirección ni el mismo modo de autenticación.

Equivocarse de familia cuesta tiempo: un 401 con un token válido, un 403 por falta del scope correcto, una lista truncada porque se ignoró la paginación. Este toil repetido acaba retrasando las correcciones y alargando el MTTR cuando la automatización falla en plena guardia (on-call).

Objetivo de este artículo: darte un mapa de referencia de las API de Dynatrace SaaS, mostrar cómo listar tú mismo los esquemas de Settings 2.0 y comentar los esquemas más útiles con ejemplos exactos de curl. Gran parte de la Environment API v2 existe también en Dynatrace Managed; la API de plataforma (AppEngine, Grail) es exclusiva de SaaS.

Las familias de la API de Dynatrace SaaS en una tabla

Quédate con dos direcciones por entorno: {env-id}.live.dynatrace.com para la Environment API clásica, y {env-id}.apps.dynatrace.com para los servicios de la plataforma. La tabla siguiente resume lo esencial.

Familia URL base Autenticación Scopes típicos Uso
Environment API v2 https://{env-id}.live.dynatrace.com/api/v2/ Api-Token (token de acceso) metrics.read, entities.read, problems.read, apiTokens.read Métricas, entidades, problemas, tokens
Settings 2.0 …/api/v2/settings/ Api-Token, token de plataforma u OAuth settings.read, settings.write (OAuth: settings:schemas:read, settings:objects:read, settings:objects:write) Toda la configuración moderna
Configuration API v1 …/api/config/v1/ Api-Token ReadConfig, WriteConfig Configuraciones antiguas no migradas
API de plataforma https://{env-id}.apps.dynatrace.com/platform/ Authorization: Bearer (OAuth o token de plataforma) storage:logs:read, storage:buckets:read, app-engine:apps:run, openpipeline:configurations:read Consultas de Grail (DQL), AppEngine, OpenPipeline
Account Management https://api.dynatrace.com/iam/v1/ Bearer mediante cliente OAuth account-uac-read, account-uac-write, iam-policies-management Usuarios, grupos, políticas

El token OAuth se obtiene en https://sso.dynatrace.com/sso/oauth2/token con el flujo client_credentials. Para diagnosticar los rechazos, consulta nuestra guía para resolver problemas con un token de API de Dynatrace.

Requisitos previos

  • Un entorno de Dynatrace SaaS (o Managed para la parte de Environment API y Settings).
  • Un token de acceso con al menos settings.read, más metrics.read y entities.read para los ejemplos siguientes.
  • Para la API de plataforma: un cliente OAuth con los scopes storage:logs:read y storage:buckets:read.
  • curl y jq; los secretos en variables de entorno, nunca en el repositorio.
export DT_ENV="https://abc12345.live.dynatrace.com"
export DT_TOKEN="dt0c01.XXXX.YYYY"   # jamais versionné

Paso 1: listar los esquemas de Settings 2.0

Settings 2.0 describe cada configuración con un esquema (schemaId) y cada instancia con un objeto. En lugar de buscar una lista fija, consulta tu propio entorno: devuelve exactamente los esquemas disponibles en él, con su versión.

curl -s "$DT_ENV/api/v2/settings/schemas" \
  -H "Authorization: Api-Token $DT_TOKEN" | jq '.totalCount, .items[0]'

Respuesta abreviada:

{
  "items": [
    {
      "displayName": "Built-in container monitoring rules",
      "latestSchemaVersion": "1.4.2",
      "maturity": "GENERAL_AVAILABILITY",
      "multiObject": true,
      "ordered": false,
      "ownerBasedAccessControl": true,
      "schemaId": "builtin:container.built-in-monitoring-rule"
    }
  ],
  "totalCount": 1
}

Los campos que debes retener: schemaId sirve en todas las llamadas siguientes, latestSchemaVersion indica la versión actual, multiObject dice si pueden coexistir varios objetos, y maturity distingue PREVIEW, EARLY_ADOPTER y GENERAL_AVAILABILITY. Las versiones evolucionan: lee siempre las de tu entorno.

Para obtener la definición completa de un esquema (propiedades, tipos, restricciones):

curl -s "$DT_ENV/api/v2/settings/schemas/builtin:alerting.profile" \
  -H "Authorization: Api-Token $DT_TOKEN" | jq '.properties | keys'

Paso 2: los esquemas más útiles

Esta es una selección de esquemas documentados para SaaS, Managed y el ActiveGate de entorno. Todos se leen con settings.read.

schemaId Qué configura Por qué es útil
builtin:alerting.profile Perfiles de alerta de los problemas Filtrar quién recibe la notificación, y cuándo, según la severidad
builtin:management-zones Zonas de gestión Dividir el entorno y los permisos por equipo
builtin:anomaly-detection.metric-events Eventos de métrica Alertas personalizadas sobre un umbral o una línea base
builtin:anomaly-detection.services Detección de anomalías de los servicios Ajustar la sensibilidad sobre los tiempos de respuesta y los fallos
builtin:failure-detection.environment.parameters Parámetros de detección de fallos Definir qué cuenta como error de servicio
builtin:logmonitoring.log-storage-settings Reglas de almacenamiento de logs Controlar qué se ingiere y, por tanto, el coste
builtin:networkzones.zones Zonas de red Dirigir el tráfico de OneAgent al ActiveGate correcto

Estos esquemas gobiernan directamente la calidad de tus alertas. Un perfil de alerta demasiado amplio despierta a la guardia para nada; un metric event mal calibrado deja pasar una degradación de SLO. Versionarlos, por ejemplo con Dynatrace Monaco, hace que cada cambio sea revisable.

Paso 3: leer y escribir objetos de Settings

Listar los objetos de un esquema requiere dos parámetros: schemaIds y scopes. El scope environment designa la configuración global; un objeto también puede apuntar a una entidad (por ejemplo un host).

curl -s "$DT_ENV/api/v2/settings/objects?schemaIds=builtin:management-zones&scopes=environment&pageSize=100" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  | jq '.items[] | {objectId, summary, schemaVersion}'

Cada objeto devuelve, entre otros, objectId, schemaId, schemaVersion, scope, value y summary. La escritura se hace con POST /api/v2/settings/objects y settings.write. Empieza siempre con una validación en seco:

curl -s -X POST "$DT_ENV/api/v2/settings/objects?validateOnly=true" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @objet.json

El cuerpo es un array de objetos con schemaId, scope y value (más schemaVersion si quieres fijar la versión). Con validateOnly=true, Dynatrace comprueba el contenido sin guardar nada: la práctica ideal en un pipeline de CI.

Paso 4: consultar los datos con la Environment API y Grail

Para las métricas clásicas, el endpoint /api/v2/metrics/query recibe un metricSelector:

curl -s -G "$DT_ENV/api/v2/metrics/query" \
  -H "Authorization: Api-Token $DT_TOKEN" \
  --data-urlencode "metricSelector=builtin:host.cpu.usage" \
  --data-urlencode "from=now-2h"

Las entidades se leen con /api/v2/entities y un entitySelector, y los problemas con /api/v2/problems (scope problems.read).

En la plataforma SaaS, las consultas DQL sobre Grail pasan por la API de consulta, con un token Bearer:

curl -s -X POST "https://abc12345.apps.dynatrace.com/platform/storage/query/v1/query:execute" \
  -H "Authorization: Bearer $DT_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "fetch logs | filter loglevel == \"ERROR\" | limit 10"}'

Si la consulta no ha terminado, la respuesta contiene un requestToken que se pasa a query:poll para recuperar el resultado. El token OAuth se solicita así:

curl -s -X POST "https://sso.dynatrace.com/sso/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$DT_CLIENT_ID&client_secret=$DT_CLIENT_SECRET&scope=storage:logs:read storage:buckets:read"

Cómo comprobar que funciona

  1. GET /api/v2/settings/schemas devuelve un totalCount distinto de cero: el token y la URL son correctos.
  2. GET /api/v2/settings/objects?schemaIds=builtin:alerting.profile&scopes=environment lista al menos el perfil por defecto.
  3. Un POST con validateOnly=true responde sin error de validación.
  4. En la interfaz, el objeto creado aparece en la pantalla de ajustes correspondiente (por ejemplo, los perfiles de alerta).

Trampas frecuentes

La paginación con nextPageKey

Las listas paginadas devuelven un nextPageKey, que vale null en la última página. Para la página siguiente, reenvía ese cursor. El script siguiente envía entonces solo nextPageKey, ya que el cursor lleva la consulta original; comprueba el comportamiento exacto de cada endpoint en su página de documentación.

KEY=""
while :; do
  if [ -z "$KEY" ]; then Q="schemaIds=builtin:management-zones&scopes=environment"; else Q="nextPageKey=$KEY"; fi
  R=$(curl -s "$DT_ENV/api/v2/settings/objects?$Q" -H "Authorization: Api-Token $DT_TOKEN")
  echo "$R" | jq -r '.items[].summary'
  KEY=$(echo "$R" | jq -r '.nextPageKey // empty')
  [ -z "$KEY" ] && break
done

Las versiones de esquema

Un esquema evoluciona: latestSchemaVersion cambia, aparecen propiedades. Un archivo JSON escrito hace seis meses puede ser rechazado. Vuelve a leer la definición del esquema antes de modificar un objeto existente y prueba con validateOnly.

La limitación de tasa

Cada entorno procesa las peticiones con un pool de hilos y una cola de espera. Cuando ambos están llenos, o cuando una petición espera más de diez segundos, la API responde 429. Espacia las llamadas, reintenta con un retraso creciente y ten presente el límite de carga útil de 1 MB en la mayoría de los endpoints.

Buenas prácticas

  • Un token por uso, con el mínimo de scopes y una fecha de caducidad.
  • Prefiere Settings 2.0 a la Configuration API v1 en cuanto exista un esquema.
  • Para la API de plataforma, usa clientes OAuth en lugar de tokens personales.
  • Versiona la configuración (Monaco o Terraform Dynatrace) y valida en CI.
  • Registra los 429 y los 403: señalan una deriva de carga o de permisos antes del incidente.

Preguntas frecuentes

¿Dónde encontrar la lista completa de los esquemas de Settings?

En tu propio entorno, con GET /api/v2/settings/schemas. La documentación oficial los describe uno por uno, pero solo tu instancia refleja los esquemas realmente disponibles y su versión.

¿Hace falta un token de acceso o un cliente OAuth?

La Environment API v2 acepta el token de acceso clásico (Api-Token). La API de plataforma en apps.dynatrace.com espera un token Bearer, obtenido por OAuth o mediante un token de plataforma. Settings 2.0 acepta ambos, con nombres de scopes distintos.

¿Existen estas API en Dynatrace Managed?

La Environment API v2 y Settings 2.0 sí, con una URL del tipo https://{dominio}/e/{env-id}/api/v2/. La API de plataforma y Grail son exclusivas de SaaS. Managed añade la API Cluster, detallada en nuestro artículo sobre la API Cluster.

Conclusión

La API de Dynatrace SaaS se vuelve sencilla en cuanto se lee como un mapa: la Environment API v2 para los datos y los tokens, Settings 2.0 para la configuración, la API de plataforma para Grail y AppEngine. Lista tus esquemas, valida antes de escribir, sigue nextPageKey y gestiona los 429: tu automatización seguirá siendo fiable. Para profundizar, consulta la documentación oficial de la API de Dynatrace.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Los ejemplos se ofrecen a título indicativo: comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión antes de usarlos en producción.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Davis CoPilot : interroger ses données en langage naturel, limites comprises

Davis CoPilot: consulta tus datos en lenguaje natural, con sus límites

Next Post
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

API de Dynatrace Managed: Cluster API v1 y v2, Environment API y esquemas de Settings disponibles

Related Posts