Migrar de la versión 1 de las APIs de uso por hora a la versión 2

Documentos > Gestión de cuentas > Guías de gestión de cuentas > Migrar de la versión 1 de las APIs de uso por hora a la versión 2

Resumen

El 1 de febrero de 2025, los endpoints de uso individual por hora por producto quedarán obsoletos en favor de la v2 de la API de uso por hora por familia de productos.

Los usuarios de las API v1 deberían reconocer conceptos familiares en la API de uso por hora v2 consolidada, sólo que representados en un formato ligeramente diferente.

Las diferencias más destacables entre estas versiones de la API son que la versión 2:

Consolida todos los productos en un único endpoint
Sigue el estándar JSON:API
Está paginada
Puede mostrar datos de varias organizaciones y regiones por solicitud

Cada diferencia se aborda con mayor detalle en las siguientes secciones.

Gamas de productos consolidadas

La API v2 introduce los conceptos de familia de productos y tipo de uso. Las familias de productos son agrupaciones de uno o más tipos de uso. Los tipos de uso son medidas de uso de una organización y un periodo de tiempo determinados. La familia de productos all indica el uso de todas las familias de productos o puedes filtrar por familias de productos específicas.

Esta lista se muestra cómo las familias de productos y los tipos de uso se corresponden con los endpoints de uso por hora v1. El tipo de uso y el punto de datos son los mismos, excepto cuando se indica explícitamente:

ENDPOINT | GAMA DE PRODUCTOS
<base_url>/api/v1/usage/hosts | infra_hosts: agent_host_count; alibaba_host_count; apm_azure_app_service_host_count; apm_host_count; aws_host_count; azure_host_count; container_count; gcp_host_count; heroku_host_count; host_count; infra_azure_app_service; opentelemetry_host_count; vsphere_host_count
<base_url>/api/v1/usage/logs | logs: billable_ingested_bytes; indexed_events_count; ingested_events_bytes; logs_live_indexed_count; logs_live_ingested_bytes; logs_rehydrated_indexed_count; logs_rehydrated_ingested_bytes
<base_url>/api/v1/usage/timeseries | timeseries: num_custom_input_timeseries; num_custom_output_timeseries; num_custom_timeseries
<base_url>/api/v1/usage/indexed-spans | indexed_spans: indexed_events_count
<base_url>/api/v1/usage/synthetics: Obsoleto. Consulta synthetics_api (API Synthetics) y synthetics_browser (navegador Synthetics) para el uso de Synthetics
<base_url>/api/v1/usage/synthetics_api | synthetics_api: check_calls_count
<base_url>/api/v1/usage/synthetics_browser | synthetics_browser: browser_check_calls_count
<base_url>/api/v1/usage/fargate | fargate: avg_profiled_fargate_tasks; tasks_count
<base_url>/api/v1/usage/aws_lambda | serverless: func_count; invocations_sum
<base_url>/api/v1/usage/rum_sessions | RUM: Consulte la guía de migración RUM para obtener instrucciones completas de asignación.
<base_url>/api/v1/usage/network_hosts | network_hosts: host_count
<base_url>/api/v1/usage/network_flows | network_flows: indexed_events_count
<base_url>/api/v1/usage/logs-by-retention | indexed_logs: Nota: En el caso de esta URL, el tipo de uso y el punto de datos son distintos, porque el valor de retención está incluido en el tipo de uso.; Tipo de uso: logs_indexed_events_<retention>_count Punto de datos: indexed_events_count; Tipo de uso: logs_live_indexed_events_<retention>_count Punto de datos: live_indexed_events_count; Tipo de uso: logs_rehydrated_indexed_events_<retention>_count Punto de datos: rehydrated_indexed_events_count; Tipo de uso: En usage_type, sustituye <retention> con uno de los siguientes parámetros: 3_day, 7_day, 15_day, 30_day, 45_day, 60_day, 90_day, 180_day, 365_day, custom Punto de datos: retention
<base_url>/api/v1/usage/analyzed_logs | analyzed_logs: analyzed_logs
<base_url>/api/v1/usage/snmp | snmp: snmp_devices
<base_url>/api/v1/usage/profiling | profiling: host_count
<base_url>/api/v1/usage/ingested-spans | ingested_spans: ingested_events_bytes
<base_url>/api/v1/usage/incident-management | incident_management: monthly_active_users
<base_url>/api/v1/usage/iot | iot: iot_device_count
<base_url>/api/v1/usage/cspm | cspm: aas_host_count; azure_host_count; compliance_host_count; container_count; host_count
<base_url>/api/v1/usage/cws | cws: cws_container_count; cws_host_count
<base_url>/api/v1/usage/dbm | dbm: dbm_host_count; dbm_queries_count
<base_url>/api/v1/usage/sds | sds: logs_scanned_bytes; total_scanned_bytes
<base_url>/api/v1/usage/ci-app | ci_app: ci_pipeline_indexed_spans; ci_test_indexed_spans; ci_visibility_pipeline_committers; ci_visibility_test_committers
<base_url>/api/v1/usage/online-archive | online_archive: online_archive_events_count
<base_url>/api/v2/usage/lambda_traced_invocations | lambda_traced_invocations: lambda_traced_invocations_count
<base_url>/api/v2/usage/application_security | application_security: app_sec_host_count
<base_url>/api/v2/usage/observability_pipelines | observability_pipelines: observability_pipelines_bytes_processed

Formato compatible con la especificación JSON:API

Los cuerpos de las respuestas y los nombres de los parámetros se ajustan a la especificación JSON:API. Todos los datos disponibles en las API v1 siguen estando disponibles. Consulta el siguiente ejemplo de asignación de la API de hosts v1 a la API de uso por hora v2.

API V1: Obtén el uso por hora de hosts y contenedores.

Solicitud

https://api.datadoghq.com/api/v1/usage/hosts?start_hr=2022-06-01T00&end_hr=2022-06-01T01

Notas

El producto es un elemento de la ruta hosts.
Los períodos de tiempo se controlan mediante los parámetros start_hr y end_hr.

Respuesta

{
  "usage": [
    {
      "agent_host_count": 1,
      "alibaba_host_count": 2,
      "apm_azure_app_service_host_count": 3,
      "apm_host_count": 4,
      "aws_host_count": 5,
      "azure_host_count": 6,
      "container_count": 7,
      "gcp_host_count": 8,
      "heroku_host_count": 9,
      "host_count": 10,
      "infra_azure_app_service": 11,
      "opentelemetry_host_count": 12,
      "vsphere_host_count": 13,
      "hour": "2022-06-01T00",
      "org_name": "Customer Inc",
      "public_id": "abc123"
    }
  ]
}

Notas

El uso dado a cada hora se representa como un objeto en la matriz de uso.
Los tipos de uso son claves en el objeto, y el uso registrado de esos tipos de uso son los valores correspondientes.
La hora, el nombre de la organización y el ID público también son campos en el objeto.

API v2: ver el uso por hora por gama de productos

Solicitud

https://api.datadoghq.com/api/v2/usage/hourly_usage?filter[timestamp][start]=2022-06-01T00&filter[timestamp][end]=2022-06-01T01&filter[product_families]=infra_hosts

Notas

El producto se incluye como un parámetro de consulta filter[product_families]=infra_hosts.
Los períodos de tiempo se controlan mediante los parámetros filter[timestamp][start] y filter[timestamp][end].

Respuesta

{
  "data": [
    {
      "attributes": {
        "org_name": "Customer Inc",
        "public_id": "abc123",
        "timestamp": "2022-06-01T00:00:00+00:00",
        "region": "us",
        "measurements": [
          {
            "usage_type": "agent_host_count",
            "value": 1
          },
          {
            "usage_type": "alibaba_host_count",
            "value": 2
          },
          {
            "usage_type": "apm_azure_app_service_host_count",
            "value": 3
          },
          {
            "usage_type": "apm_host_count",
            "value": 4
          },
          {
            "usage_type": "aws_host_count",
            "value": 5
          },
          {
            "usage_type": "azure_host_count",
            "value": 6
          },
          {
            "usage_type": "container_count",
            "value": 7
          },
          {
            "usage_type": "gcp_host_count",
            "value": 8
          },
          {
            "usage_type": "heroku_host_count",
            "value": 9
          },
          {
            "usage_type": "host_count",
            "value": 10
          },
          {
            "usage_type": "infra_azure_app_service",
            "value": 11
          },
          {
            "usage_type": "opentelemetry_host_count",
            "value": 12
          },
          {
            "usage_type": "vsphere_host_count",
            "value": 13
          }
        ],
        "product_family": "infra_hosts"
      },
      "type": "usage_timeseries",
      "id": "ec3e0318b98d15c2ae8125e8bda0ff487cd08d80b120fb340c9322ee16f28629"
    }
  ]
}

Notas

Los objetos de la matriz de datos representan el uso por hora de cada producto y cada organización.
- Las APIs v1 no eran compatibles con varios productos o varias organizaciones por solicitud.
Las mediciones de uso se representan en la matriz measurements anidada.
Los objetos de medición de uso tienen los campos usage_type y value.
hour, org_name y public_id también son campos en el objeto attributes.

Paginación

La API v2 de uso por hora está paginada. Las respuestas tienen un límite de 500 páginas, donde cada página contiene los datos de uso de una gama de productos, para una hora y una organización. La paginación permite que la API sea compatible con otras funciones, por ejemplo, varios productos por solicitud, varias organizaciones por solicitud y rangos de tiempo ilimitados.

Si un resultado tiene más páginas, el ID de registro de la página siguiente se muestra en el campo meta.pagination.next_record_id. Luego, los clientes deberán incluir ese ID en el parámetro pagination[next_record_id]. Si el el campo meta.pagination.next_record_id no está definido, no hay más páginas que consultar.

Ejemplo de código

response := GetHourlyUsage(start_time, end_time, product_families)
cursor := response.metadata.pagination.next_record_id
WHILE cursor != null BEGIN
sleep(5 seconds)  # Avoid running into rate limit
response := GetHourlyUsage(start_time, end_time, product_families, next_record_id=cursor)
cursor := response.metadata.pagination.next_record_id
END

Respuestas de varias organizaciones

La API v2 permite recuperar los datos de uso de todas tus organizaciones secundarias de todas las regiones en una solicitud. Utiliza el parámetro filter[include_descendants] para solicitar datos de organizaciones secundarias.

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Planificación y ajustes de usoDOCUMENTACIÓN