Passer de la version 1 à la version 2 des API d'utilisation horaire

Docs > Gestion de compte > Guides sur la gestion de compte > 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_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
<url_de_base>/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
<url_de_base>/api/v1/usage/timeseries | timeseries: num_custom_input_timeseries; num_custom_output_timeseries; num_custom_timeseries
<url_de_base>/api/v1/usage/indexed-spans | indexed_spans: indexed_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_api: check_calls_count
<url_de_base>/api/v1/usage/synthetics_browser | synthetics_browser: browser_check_calls_count
<url_de_base>/api/v1/usage/fargate | fargate: avg_profiled_fargate_tasks; tasks_count
<url_de_base>/api/v1/usage/aws_lambda | serverless: func_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_hosts: host_count
<url_de_base>/api/v1/usage/network_flows | network_flows: indexed_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_logs: analyzed_logs
<url_de_base>/api/v1/usage/snmp | snmp: snmp_devices
<url_de_base>/api/v1/usage/profiling | profiling: host_count
<url_de_base>/api/v1/usage/ingested-spans | ingested_spans: ingested_events_bytes
<url_de_base>/api/v1/usage/incident-management | incident_management: monthly_active_users
<url_de_base>/api/v1/usage/iot | iot: iot_device_count
<url_de_base>/api/v1/usage/cspm | cspm: aas_host_count; azure_host_count; compliance_host_count; container_count; host_count
<url_de_base>/api/v1/usage/cws | cws: cws_container_count; cws_host_count
<url_de_base>/api/v1/usage/dbm | dbm: dbm_host_count; dbm_queries_count
<url_de_base>/api/v1/usage/sds | sds: logs_scanned_bytes; total_scanned_bytes
<url_de_base>/api/v1/usage/ci-app | ci_app: ci_pipeline_indexed_spans; ci_test_indexed_spans; ci_visibility_pipeline_committers; ci_visibility_test_committers
<url_de_base>/api/v1/usage/online-archive | online_archive: online_archive_events_count
<url_de_base>/api/v2/usage/lambda_traced_invocations | lambda_traced_invocations: lambda_traced_invocations_count
<url_de_base>/api/v2/usage/application_security | application_security: app_sec_host_count
<url_de_base>/api/v2/usage/observability_pipelines | observability_pipelines: observability_pipelines_bytes_processed

Format conforme à la spécification JSON:API

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.

Pagination

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:

Paramètres de formule et d'utilisationDOCUMENTATION