Migrar de la versión 1 de las APIs de uso por hora a la versión 2
Resumen
Los usuarios de la versión 1 de las APIs deberían reconocer conceptos similares en la versión 2 de la API de uso por hora,
aunque representados de forma algo 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 versión 2 de la API introduce los conceptos de gama de productos y tipo de uso. Las gamas de productos son
agrupaciones de uno o varios tipos de uso. Los tipos de uso son mediciones del uso de una organización
y un periodo de tiempo concretos. El conjunto inicial de gamas de productos se corresponde en su mayor parte con la versión 1 de las APIs,
con la asignación completa indicada a continuación. Además, existe una gama de productos all
especial que recopila
el uso del resto de gamas de productos.
Las gamas y los tipos de uso:
- all (todos)
- Contiene todas las demás gamas de productos
- analyzed_logs (logs analizados)
- application_security (seguridad de la aplicación)
- audit_trail (traza de auditoría)
- serverless
func_count
invocations_sum
- ci_app (app CI)
ci_pipeline_indexed_spans
ci_test_indexed_spans
ci_visibility_pipeline_committers
ci_visibility_test_committers
- cloud_cost_management (gestión de costes en la nube)
- csm_container_enterprise
cws_count
compliance_count
total_count
- csm_host_enterprise
total_host_count
compliance_hosts
cws_hosts
aas_host_count
azure_host_count
aws_host_count
gcp_host_count
- cspm
aas_host_count
azure_host_count
compliance_host_count
container_count
host_count
- cws
cws_container_count
cws_host_count
- dbm
dbm_host_count
dbm_queries_count
- fargate
avg_profiled_fargate_tasks
tasks_count
- 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
- incident_management
- indexed_logs
logs_indexed_events_3_day_count
logs_live_indexed_events_3_day_count
logs_rehydrated_indexed_events_3_day_count
logs_indexed_events_7_day_count
logs_live_indexed_events_7_day_count
logs_rehydrated_indexed_events_7_day_count
logs_indexed_events_15_day_count
logs_live_indexed_events_15_day_count
logs_rehydrated_indexed_events_15_day_count
logs_indexed_events_30_day_count
logs_live_indexed_events_30_day_count
logs_rehydrated_indexed_events_30_day_count
logs_indexed_events_45_day_count
logs_live_indexed_events_45_day_count
logs_rehydrated_indexed_events_45_day_count
logs_indexed_events_60_day_count
logs_live_indexed_events_60_day_count
logs_rehydrated_indexed_events_60_day_count
logs_indexed_events_90_day_count
logs_live_indexed_events_90_day_count
logs_rehydrated_indexed_events_90_day_count
logs_indexed_events_180_day_count
logs_live_indexed_events_180_day_count
logs_rehydrated_indexed_events_180_day_count
logs_indexed_events_360_day_count
logs_live_indexed_events_360_day_count
logs_rehydrated_indexed_events_360_day_count
logs_indexed_events_custom_day_count
logs_live_indexed_events_custom_day_count
logs_rehydrated_indexed_events_custom_day_count
- indexed_spans
indexed_events_count
ingested_spans
ingested_events_bytes
- iot
- lambda_traced_invocations
lambda_traced_invocations_count
- logs
billable_ingested_bytes
indexed_events_count
ingested_events_bytes
logs_forwarding_events_bytes
logs_live_indexed_count
logs_live_ingested_bytes
logs_rehydrated_indexed_count
logs_rehydrated_ingested_bytes
- network_flows
- network_hosts
- observability_pipelines
observability_pipelines_bytes_processed
- online_archive
online_archive_events_count
- profiling
avg_container_agent_count
host_count
- rum
browser_rum_units
mobile_rum_units
rum_units
- rum_browser_sessions
replay_session_count
session_count
- rum_mobile_sessions
session_count
session_count_android
session_count_ios
session_count_reactnative
session_count_flutter
- sds
logs_scanned_bytes
total_scanned_bytes
- snmp
- synthetics_api
- synthetics_browser
browser_check_calls_count
- synthetics_mobile
- timeseries
num_custom_input_timeseries
num_custom_output_timeseries
num_custom_timeseries
Esta lista muestra cómo se asignan las gamas y los tipos de uso anteriores a los endpoints de uso por hora de la versión 1. El tipo de uso y el punto de datos son lo mismo, excepto cuando se especifique expresamente lo contrario:
- ENDPOINT | GAMA DE PRODUCTOS
<base_url>/api/v1/usage/hosts
| infra_hostsagent_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
| logsbillable_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
| timeseriesnum_custom_input_timeseries
num_custom_output_timeseries
num_custom_timeseries
<base_url>/api/v1/usage/indexed-spans
| indexed_spansindexed_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_apicheck_calls_count
<base_url>/api/v1/usage/synthetics_browser
| synthetics_browserbrowser_check_calls_count
<base_url>/api/v1/usage/fargate
| fargateavg_profiled_fargate_tasks
tasks_count
<base_url>/api/v1/usage/aws_lambda
| serverlessfunc_count
invocations_sum
<base_url>/api/v1/usage/rum_sessions?type=browser
| rum_browser_sessionsreplay_session_count
session_count
<base_url>/api/v1/usage/rum_sessions?type=mobile
| rum_mobile_sessionssession_count
session_count_android
session_count_ios
session_count_reactnative
<base_url>/api/v1/usage/network_hosts
| network_hostshost_count
<base_url>/api/v1/usage/network_flows
| network_flowsindexed_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_logsanalyzed_logs
<base_url>/api/v1/usage/snmp
| snmpsnmp_devices
<base_url>/api/v1/usage/profiling
| profilinghost_count
<base_url>/api/v1/usage/ingested-spans
| ingested_spansingested_events_bytes
<base_url>/api/v1/usage/incident-management
| incident_managementmonthly_active_users
<base_url>/api/v1/usage/iot
| iotiot_device_count
<base_url>/api/v1/usage/cspm
| cspmaas_host_count
azure_host_count
compliance_host_count
container_count
host_count
<base_url>/api/v1/usage/audit_logs
| audit_logslines_indexed
<base_url>/api/v1/usage/cws
| cwscws_container_count
cws_host_count
<base_url>/api/v1/usage/dbm
| dbmdbm_host_count
dbm_queries_count
<base_url>/api/v1/usage/sds
| sdslogs_scanned_bytes
total_scanned_bytes
<base_url>/api/v1/usage/rum
| rumbrowser_rum_units
mobile_rum_units
rum_units
<base_url>/api/v1/usage/ci-app
| ci_appci_pipeline_indexed_spans
ci_test_indexed_spans
ci_visibility_pipeline_committers
ci_visibility_test_committers
<base_url>/api/v1/usage/online-archive
| online_archiveonline_archive_events_count
<base_url>/api/v2/usage/lambda_traced_invocations
| lambda_traced_invocationslambda_traced_invocations_count
<base_url>/api/v2/usage/application_security
| application_securityapp_sec_host_count
<base_url>/api/v2/usage/observability_pipelines
| observability_pipelinesobservability_pipelines_bytes_processed
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 la versión 1 de las APIs siguen estando disponibles. Consulta el siguiente ejemplo de asignación de la API de hosts de la versión 1
a la API de uso por hora de la versión 2.
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.
Leer más
Additional helpful documentation, links, and articles: