Passer de la version 1 à la version 2 des API d'utilisation horaire
Résumé
Le 1er février 2025, les endpoints individuels d’utilisation horaire par produit seront obsolètes au profit de l’API v2 utilisation horaire par famille de produits.
Les utilisateurs de la version 1 des API devraient reconnaître dans la version 2 des API d’utilisation horaire consolidée les concepts auxquels ils sont habitués, malgré un format légèrement différent.
Voici les différences les plus notables entre les versions 1 et 2. La version 2 :
- regroupe tous les produits au sein d’un même endpoint ;
- est conforme à la spécification JSON:API ;
- est paginée ;
- peut renvoyer des données pour plusieurs organisations et régions à l’aide d’une même requête.
Chacune de ces différences est abordée plus en détail dans les rubriques qui suivent.
Familles de produits consolidées
L’API v2 introduit les concepts de famille de produits et de type d’utilisation. Les familles de produits regroupent
un ou plusieurs types d’utilisation. Les types d’utilisation correspondent aux mesures d’utilisation pour une organisation
et une période données. La famille de produits all
récupère l’utilisation de toutes les familles de produits, ou vous pouvez filtrer par familles de produits spécifiques.
La liste ci-dessous montre la correspondance entre les familles de produits et les types d’utilisation avec les endpoints v1 d’utilisation horaire. Le type d’utilisation et le point de données sont identiques, sauf indication explicite contraire :
- ENDPOINT | FAMILLE DE PRODUITS
<url_de_base>/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
<url_de_base>/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
<url_de_base>/api/v1/usage/timeseries
| timeseriesnum_custom_input_timeseries
num_custom_output_timeseries
num_custom_timeseries
<url_de_base>/api/v1/usage/indexed-spans
| indexed_spansindexed_events_count
<url_de_base>/api/v1/usage/synthetics
- Obsolète. Voir synthetics_api et synthetics_browser pour l’utilisation de Synthetic.
<url_de_base>/api/v1/usage/synthetics_api
| synthetics_apicheck_calls_count
<url_de_base>/api/v1/usage/synthetics_browser
| synthetics_browserbrowser_check_calls_count
<url_de_base>/api/v1/usage/fargate
| fargateavg_profiled_fargate_tasks
tasks_count
<url_de_base>/api/v1/usage/aws_lambda
| serverlessfunc_count
invocations_sum
<base_url>/api/v1/usage/rum_sessions
| rum- Consultez le guide de migration RUM pour les instructions complètes de mappage
<url_de_base>/api/v1/usage/network_hosts
| network_hostshost_count
<url_de_base>/api/v1/usage/network_flows
| network_flowsindexed_events_count
<url_de_base>/api/v1/usage/logs-by-retention
| indexed_logs- Remarque : le type d’utilisation et le point de données sont distincts pour cette URL, car la valeur de rétention est incluse dans le type d’utilisation.
- Type d’utilisation :
logs_indexed_events_<rétention>_count
Point de données : indexed_events_count
- Type d’utilisation :
logs_live_indexed_events_<rétention>_count
Point de données : live_indexed_events_count
- Type d’utilisation :
logs_rehydrated_indexed_events_<rétention>_count
Point de données : rehydrated_indexed_events_count
- Type d’utilisation : dans
usage_type
, remplacez <rétention>
par l’une de ces valeurs : 3_day
, 7_day
, 15_day
, 30_day
, 45_day
, 60_day
, 90_day
, 180_day
, 365_day
ou custom
Point de données : retention
<url_de_base>/api/v1/usage/analyzed_logs
| analyzed_logsanalyzed_logs
<url_de_base>/api/v1/usage/snmp
| snmpsnmp_devices
<url_de_base>/api/v1/usage/profiling
| profilinghost_count
<url_de_base>/api/v1/usage/ingested-spans
| ingested_spansingested_events_bytes
<url_de_base>/api/v1/usage/incident-management
| incident_managementmonthly_active_users
<url_de_base>/api/v1/usage/iot
| iotiot_device_count
<url_de_base>/api/v1/usage/cspm
| cspmaas_host_count
azure_host_count
compliance_host_count
container_count
host_count
<url_de_base>/api/v1/usage/cws
| cwscws_container_count
cws_host_count
<url_de_base>/api/v1/usage/dbm
| dbmdbm_host_count
dbm_queries_count
<url_de_base>/api/v1/usage/sds
| sdslogs_scanned_bytes
total_scanned_bytes
<url_de_base>/api/v1/usage/ci-app
| ci_appci_pipeline_indexed_spans
ci_test_indexed_spans
ci_visibility_pipeline_committers
ci_visibility_test_committers
<url_de_base>/api/v1/usage/online-archive
| online_archiveonline_archive_events_count
<url_de_base>/api/v2/usage/lambda_traced_invocations
| lambda_traced_invocationslambda_traced_invocations_count
<url_de_base>/api/v2/usage/application_security
| application_securityapp_sec_host_count
<url_de_base>/api/v2/usage/observability_pipelines
| observability_pipelinesobservability_pipelines_bytes_processed
Le corps des réponses et les noms des paramètres sont conformes à la spécification JSON:API. Toutes les données
disponibles avec la version 1 des API le sont toujours. L’exemple ci-dessous illustre le mappage de l’API Hosts v1
avec l’API d’utilisation horaire v2.
API v1 : Récupérer l’utilisation horaire pour les hosts et conteneurs
Requête
https://api.datadoghq.com/api/v1/usage/hosts?start_hr=2022-06-01T00&end_hr=2022-06-01T01
Remarques
- Le produit est un élément du chemin
hosts
. - Les limites horaires sont contrôlées par les paramètres
start_hr
et end_hr
.
Réponse
{
"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"
}
]
}
Remarques
- L’utilisation pour chaque heure est représentée sous la forme d’un objet dans le tableau d’utilisation.
- Les types d’utilisation sont représentés par des clés dans l’objet, et l’utilisation mesurée pour ces types d’utilisation est indiquée par les valeurs correspondantes.
- L’objet contient également des champs pour l’heure, le nom de l’organisation et l’ID public.
API v2 : Récupérer l’utilisation horaire par famille de produits
Requête
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
Remarques
- Le produit est transmis sous la forme d’un paramètre de requête, à savoir
filter[product_families]=infra_hosts
. - Les limites horaires sont contrôlées par les paramètres
filter[timestamp][start]
et filter[timestamp][end]
.
Réponse
{
"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"
}
]
}
Remarques
- Les objets du tableau de données représentent l’utilisation horaire pour chaque produit et chaque organisation.
- Avec la version 1, les API ne prenaient en charge qu’un produit ou qu’une organisation par requête.
- Les mesures d’utilisation sont représentées dans le tableau
measurements
imbriqué. - Les objets de mesure d’utilisation contiennent les champs
usage_type
et value
. - L’objet
attributes
contient également les champs hour
, org_name
et public_id
.
Les API d’utilisation horaire v2 sont paginées. Les réponses sont limitées à 500 pages, chacune d’elles contenant les données d’utilisation d’une seule famille de produits, pour une heure et une organisation. La pagination permet aux API de prendre en charge d’autres fonctionnalités, comme l’intégration de plusieurs produits par requête, l’intégration de plusieurs organisations par requête et des plages horaires illimitées.
Si le nombre de pages d’un résultat est supérieur à cette limite, l’ID d’enregistrement de la page suivante est renvoyé dans le champ meta.pagination.next_record_id
. Les clients doivent alors transmettre cet ID via le paramètre pagination[next_record_id]
. Il n’y a aucune page supplémentaire à récupérer si le champ meta.pagination.next_record_id
n’est pas défini.
Exemple de code
response := GetHourlyUsage(start_time, end_time, product_families)
cursor := response.metadata.pagination.next_record_id
WHILE cursor != null BEGIN
sleep(5 seconds) # Éviter d'atteindre la limite de débit
response := GetHourlyUsage(start_time, end_time, product_families, next_record_id=cursor)
cursor := response.metadata.pagination.next_record_id
END
Réponses pour plusieurs organisations
La version 2 des API prend en charge la récupération des données d’utilisation de toutes vos organisations enfant dans toutes les régions à l’aide d’une même requête. Utilisez le paramètre filter[include_descendants]
pour récupérer les données des organisations enfant.
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles: