Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

À propos des rapports sur les coûts et l'utilisation

Pour vous aider à comprendre et à gérer vos coûts Google Cloud , l'API App Optimize vous permet de créer des rapports avec des paramètres spécifiques tels que le champ d'application, les dimensions, la plage de dates et les filtres.

Pour récupérer les données de coût et d'utilisation avec l'API App Optimize, vous devez d'abord créer une ressource report dans un projet Google Cloud de votre choix. Cette ressource sert de définition persistante pour les données que vous souhaitez analyser.

Le projet qui stocke votre rapport ne doit pas nécessairement être la source des données du rapport. Vous pouvez créer un rapport dans un projet pour analyser les données d'un autre projet source ou d'une application App Hub.

Une fois que vous avez créé un rapport, l'API génère les données demandées de manière asynchrone. Vous utilisez ensuite le nom de ressource du rapport pour récupérer l'ensemble de données résultant lorsque le rapport est prêt.

Le workflow est donc le suivant :

Vous créez un rapport en spécifiant vos critères.
Le système traite cette demande de manière asynchrone.
Une fois l'opération terminée, vous lisez les données obtenues.

Ce document décrit en détail la structure et les paramètres configurables des rapports de l'API App Optimize, y compris les dimensions, les métriques et les options de filtrage disponibles. Il explique également le format des données renvoyées.

Pour en savoir plus sur les limites concernant les coûts et l'utilisation, consultez Comprendre les données.

Définir un rapport

Pour créer un rapport, vous devez définir une ressource Report avec les paramètres de configuration suivants, qui sont décrits dans les sous-sections suivantes :

Paramètre	Type	Description
`scopes`	Tableau	Projet ou application App Hub à analyser. Vous devez fournir exactement un élément de portée.
`dimensions`	Tableau	Attributs permettant de récupérer et de regrouper les données, y compris les regroupements temporels.
`metrics`	Tableau	Mesures spécifiques à renvoyer.
`filter`	Chaîne	Expression CEL (Common Expression Language) permettant d'affiner les données, y compris les plages de dates.

Niveaux d'accès

Le champ scopes définit l'ensemble des ressources que l'API App Optimize analysera. Bien que le champ soit un tableau, vous devez spécifier un seul élément, qui peut être un projet ou une application App Hub :

project : chaîne représentant un projet Google Cloud . Il doit être au format suivant :
```
projects/PROJECT_ID
```
Remplacez PROJECT_ID par l'ID du projet Google Cloud à analyser. Par exemple, projects/my-project-1.
application : chaîne représentant le nom complet de la ressource d'une application App Hub. Il doit être au format suivant :
```
projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
```
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet hôte App Hub.
- LOCATION : région de l'application App Hub, par exemple us-central1.
- APPLICATION_ID : ID de l'application App Hub.
Par exemple, projects/my-host-proj/locations/us-central1/applications/my-app.

Voici des exemples de tableaux scopes au format JSON pour une demande de création de rapport, avec un seul élément de portée :

Définition du champ d'application par projet :

"scopes": [
  {
    "project": "projects/my-project-1"
  }
]

Définition du champ d'application par application :

"scopes": [
  {
    "application": "projects/my-host-proj/locations/us-central1/applications/my-app"
  }
]

Dimensions

Les dimensions déterminent les données renvoyées et la façon dont elles sont regroupées. Par exemple, si vous sélectionnez project et product_display_name, le résultat contient une ligne pour chaque combinaison unique de valeurs de nom de projet et de produit trouvée dans les données.

Voici un tableau des dimensions acceptées :

Dimension	Type	Description	Exemple de valeur
`project`	STRING	ID du projet Google Cloud .	`projects/my-project`
`application`	STRING	L'application App Hub.	`projects/my-project/locations/us-central1/applications/my-app`
`service_or_workload`	STRING	Service ou charge de travail App Hub.	`projects/my-project/locations/us-central1/applications/my-app/services/my-service`
`resource`	STRING	Nom complet de la ressource.	`//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1`
`resource_type`	STRING	Type de ressource de l'API.	`compute.googleapis.com/Instance`
`location`	STRING	Région ou emplacement multirégional Google Cloud .	`us-east1`
`sku`	STRING	ID du SKU de facturation.	`4496-8C0D-228F`
`product_display_name`	STRING	Nom du produit Google Cloud .	`Compute Engine`
`month`	STRING	Année et mois.	`2024-01`
`day`	STRING	L'année, le mois et le jour.	`2024-01-10`
`hour`	STRING	Année, mois, jour et heure.	`2024-01-10T00`

La dimension location représente la Google Cloud région ou l'emplacement multirégional auxquels les coûts et l'utilisation sont attribués. La façon dont cette zone géographique est signalée dépend des paramètres de localisation des ressources incluses dans le champ d'application du rapport :

Pour les ressources déployées dans une zone spécifique, comme us-central1-a, les coûts et l'utilisation sont agrégés et attribués à la région parente. Dans cet exemple, la dimension location afficherait us-central1.
Pour les ressources déployées dans une région, comme us-central1, la dimension location reflète cette région spécifique.
Pour les ressources déployées ou configurées pour une région multiple, telle que us, la dimension location reflète cette région multiple.

Dimensions temporelles

Pour agréger les résultats par période, incluez au moins une dimension temporelle (par exemple, month, day ou hour) dans la liste dimensions. N'oubliez pas :

Toutes les dimensions temporelles utilisent le fuseau horaire du Pacifique et respectent l'heure d'été.
Les formats suivent la norme ISO 8601.
Si la période du filter ne correspond pas parfaitement à la précision de la dimension temporelle sélectionnée, elle est étendue pour couvrir les périodes entières. Par exemple, si vous filtrez une partie d'une journée avec dimension: ["month"], les données de l'ensemble du mois seront incluses.

Métriques

Les métriques sont les valeurs quantitatives que vous souhaitez mesurer pour chaque groupe défini par vos dimensions.

Métriques sur les coûts

Métrique de coût	Type	Description
`cost`	RECORD	Coût monétaire dans la devise demandée.
`network_cost`	RECORD	Coût total de la mise en réseau, y compris le transfert et le traitement des données.
`network_cost_standard_internet`	RECORD	Coût total du transfert de données pour le niveau Standard.
`network_cost_premium_internet`	RECORD	Coût total du transfert de données pour le niveau Premium.
`network_cost_inter_region`	RECORD	Coût total du transfert de données interrégional.
`network_cost_inter_zone`	RECORD	Coût total du transfert de données interzones.
`network_cost_load_balancing_inbound`	RECORD	Coût total du traitement des données entrantes par Cloud Load Balancing.
`network_cost_load_balancing_outbound`	RECORD	Coût total du traitement des données sortantes par Cloud Load Balancing.
`network_cost_interconnect_inbound`	RECORD	Coût total du transfert de données entrant via Cloud Interconnect.
`network_cost_interconnect_outbound`	RECORD	Coût total du transfert de données sortantes via Cloud Interconnect.
`resource_cost`	RECORD	Coût total des ressources.

Métriques d'utilisation

Métrique d'utilisation	Type	Description
`cpu_mean_utilization`	FLOAT64	Utilisation moyenne du processeur (de 0,0 à 1,0).
`cpu_p95_utilization`	FLOAT64	Utilisation du processeur au 95e centile (de 0,0 à 1,0).
`cpu_usage_core_seconds`	INT64	Travail CPU total effectué.
`cpu_allocation_core_seconds`	INT64	Capacité totale de processeur provisionnée.
`memory_mean_utilization`	FLOAT64	Utilisation moyenne de la mémoire (de 0,0 à 1,0).
`memory_p95_utilization`	FLOAT64	Utilisation de la mémoire au 95e centile (de 0,0 à 1,0).
`memory_usage_byte_seconds`	INT64	Mémoire totale utilisée au fil du temps.
`memory_allocation_byte_seconds`	INT64	Mémoire totale provisionnée au fil du temps.

Combinaisons valides

Dans l'API App Optimize, il n'est pas possible de combiner n'importe quelle dimension avec n'importe quelle métrique. Le tableau suivant présente des exemples de combinaisons de dimensions valides et les métriques que vous pouvez utiliser avec elles. L'API renverra une erreur si une combinaison non valide est demandée. Reportez-vous à cette erreur pour connaître les combinaisons valides.

Dimensions	La métrique `cost` est acceptée.	La métrique `cpu_mean_utilization` est acceptée.
`application`, `product_display_name`
`application`
`location`, `product_display_name`, `project`, `resource`, `resource_type`, `sku`
`location`, `product_display_name`, `project`, `resource` et `resource_type`
`location`, `product_display_name`, `project`, `service_or_workload`
`location`, `product_display_name`, `project`, `sku`
`product_display_name`, `project`
`product_display_name`, `resource_type`
`product_display_name`, `resource`
`product_display_name`
`project`

Filtres

Utilisez le champ filter pour affiner les données à l'aide d'une chaîne CEL. Vous pouvez créer vos expressions de filtre à l'aide de l'un des champs listés dans le tableau Dimensions.

Le filtrage doit respecter les contraintes suivantes :

Tous les prédicats de champ de chaîne doivent utiliser des correspondances exactes de chaîne. Par exemple, location == 'us-east1'.
Plusieurs prédicats faisant référence au même champ de chaîne doivent être joints à l'aide de l'opérateur logique OR, ||. Exemple :location == 'us-east1' || location == 'us-west1'
Tous les autres prédicats doivent être associés à l'aide de l'opérateur logique AND, &&.
Un prédicat sur une dimension temporelle, tel que day, spécifiant l'heure de début, doit utiliser la comparaison supérieure ou égale à, >=.
Un prédicat sur une dimension temporelle spécifiant l'heure de fin doit utiliser la comparaison "inférieur à", <.

Période

Si filter omet les dimensions temporelles (month, day, hour), le rapport utilise par défaut une période de sept jours se terminant à minuit (heure du Pacifique) la veille, en tenant compte de l'heure d'été. La plage de dates maximale est de 90 jours avant la date actuelle, et l'heure de début doit être comprise dans cette période de 90 jours.

Par exemple, si l'heure actuelle dans le fuseau horaire du Pacifique est 2026-01-05T12:00:00, la plage par défaut est comprise entre 2025-12-29T00:00:00 et 2026-01-05T00:00:00, toujours dans le fuseau horaire du Pacifique. L'heure de début la plus proche pour la période est 2025-10-07T00:00:00.

Les métriques Cloud Run ne sont disponibles que pendant six semaines avant la date actuelle.

Exemples de filtres

Voici quelques exemples de la façon dont vous pouvez structurer vos chaînes de filtre CEL :

Pour filtrer les données du rapport pour un type de ressource spécifique, utilisez l'opérateur == sur la dimension resource_type :
```
resource_type == 'compute.googleapis.com/Instance'
```
Pour n'inclure que les données d'un seul établissement, filtrez la dimension location :
```
location == 'us-east1'
```
Pour inclure des données provenant d'une liste spécifique d'emplacements, utilisez l'opérateur || pour combiner les conditions sur la dimension location :
```
location == 'us-east1' || location == 'us-west1'
```
Pour obtenir des données dans une plage de temps spécifique avec une précision horaire, vous pouvez filtrer la dimension hour. Cet exemple inclut les données du début de la période 2024-01-01 jusqu'à 2024-02-01 (non inclus) :
```
hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```
Pour filtrer les jours entiers, utilisez la dimension day. Notez que les limites de jour sont interprétées en heure du Pacifique. Il est donc recommandé de spécifier le décalage. Cet exemple inclut toutes les données du 15 mars 2024 et du 16 mars 2024 :
```
day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
```
De même, vous pouvez filtrer par mois calendaire à l'aide de la dimension month, en gardant à l'esprit l'heure du Pacifique pour les limites exactes. Cet exemple inclut toutes les données d'octobre et de novembre 2025 :
```
month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
```
Pour obtenir les données des 72 dernières heures, utilisez les fonctions now() et duration() sur la dimension hour :
```
hour >= now() - duration('72h')
```
Pour obtenir les données des sept derniers jours, vous pouvez utiliser duration() avec la dimension hour :
```
hour >= now() - duration('168h')
```
Pour filtrer les données sur un mois civil spécifique, comme le mois précédent, vous devez calculer les codes temporels de début et de fin dans le code de votre application. Vous insérez ensuite ces codes temporels calculés dans l'expression CEL. Conceptuellement, cela peut se présenter comme suit, avec un filtrage sur la dimension day :
```
day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
```
Remplacez les éléments suivants :
- START_OF_LAST_MONTH : chaîne de code temporel ISO 8601 représentant le tout début du mois précédent dans le fuseau horaire du Pacifique, par exemple 2025-12-01T00:00:00-08:00.
- START_OF_THIS_MONTH : chaîne de code temporel ISO 8601 représentant le tout début du mois en cours dans le fuseau horaire du Pacifique, par exemple 2026-01-01T00:00:00-08:00.
Vous devez calculer ces chaînes de code temporel exactes dans le code de votre application, en tenant compte de la date actuelle, du fuseau horaire (heure du Pacifique) et des transitions de l'heure d'été.
Vous pouvez combiner des filtres de chaîne et de période à l'aide de l'opérateur &&. Cet exemple filtre les données pour deux zones géographiques au cours d'une période de deux mois spécifique :
```
(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```

Voici un exemple plus complexe combinant resource_type, project et une plage de temps basée sur day :

resource_type == 'compute.googleapis.com/Instance' && project == 'projects/my-project' && day >= timestamp('2025-01-01T00:00:00-08:00') && day < timestamp('2025-02-01T00:00:00-08:00')

Structure des données du rapport

Lorsque vous lisez un rapport, le service renvoie les données sous la forme columns et rows.

Colonnes

Le tableau columns décrit le schéma des données, dans l'ordre dans lequel chaque champ apparaît dans rows. Chaque objet du tableau columns comporte un name, un type et parfois un columns imbriqué si le type est RECORD.

Les dimensions que vous avez demandées s'affichent sous forme de champs de type STRING.
Les métriques que vous avez demandées s'affichent sous forme de champs avec des types tels que INT64, FLOAT64 ou RECORD pour les types complexes tels que cost.

Par exemple, avec l'API REST, si vous demandez dimensions: ["application", "product_display_name"] et metrics: ["cost", "cpu_mean_utilization"], l'API App Optimize génère en réponse un tableau columns comme celui-ci :

"columns": [
  {
    "name": "application",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "product_display_name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "cost",
    "type": "RECORD",
    "mode": "NULLABLE",
    "columns": [
      {
        "name": "currency_code",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "units",
        "type": "INT64",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "cpu_mean_utilization",
    "type": "FLOAT64",
    "mode": "NULLABLE"
  }
]

Lignes

Le champ rows contient les données réelles. Chaque ligne est un tableau de valeurs représentant un seul enregistrement. L'ordre des valeurs dans chaque tableau interne correspond directement à l'ordre des champs définis dans le tableau columns.

En reprenant l'exemple où application, product_display_name, cost et cpu_mean_utilization ont été demandés à l'API REST, une seule ligne du tableau rows généré peut se présenter comme suit :

"rows": [
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-central1/applications/my-app",
    "Compute Engine",
    {
      "currency_code": "USD",
      "units": "12",
      "nanos": 750000000
    },
    0.65
  ],
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-east1/applications/another-app",
    "Cloud Storage",
    {
      "currency_code": "USD",
      "units": "5",
      "nanos": 200000000
    },
    0.15
  ]
]

Le tableau suivant montre comment les valeurs d'un tableau de ligne unique sont mises en correspondance avec le schéma défini dans le tableau columns, en utilisant l'index de la valeur dans le tableau de ligne :

Index dans la ligne	Colonne correspondante	Type	Exemple de valeur
0	`application`	STRING	`"//apphub.googleapis.com/.../applications/my-app"`
1	`product_display_name`	STRING	`"Cloud Storage"`
2	`cost`	RECORD	`{ "currency_code": "USD", "units": "10", ... }`
3	`cpu_mean_utilization`	FLOAT64	`0.65`

Chaque élément de la liste rows est un tableau dans lequel l'ordre des valeurs correspond à l'ordre des définitions de champ dans le tableau columns. Ainsi, la valeur à l'index n dans un tableau de lignes donné correspond à la colonne définie à l'index n dans le tableau columns.

Interpréter les métriques sur les coûts

Lorsqu'un rapport inclut la métrique cost, la valeur est renvoyée sous la forme d'un RECORD contenant les champs suivants, en fonction du type standard google.type.Money :

Champ	Type	Description
`currency_code`	STRING	Code de devise ISO 4217 à trois lettres (par exemple, "EUR").
`units`	INT64	Unités entières du montant.
`nanos`	INT64	Nombre de nano-unités (10^-9) du montant. Cette valeur doit être comprise entre -999 999 999 et +999 999 999 (inclus).

Pour obtenir la valeur monétaire complète, vous devez combiner les champs units et nanos. Le champ nanos représente la partie fractionnaire de la valeur monétaire. Exemple :

Si currency_code est "USD", units est 106 et nanos est 321590000 : La valeur est 106 + (321 590 000 / 1 000 000 000) = 106,32159 USD.
Si currency_code est défini sur "EUR", units sur 5 et nanos sur 750000000 : La valeur est 5 + (750 000 000 / 1 000 000 000) = 5,75 EUR.

Vous utiliserez généralement une bibliothèque de mise en forme standard des devises pour afficher cette valeur dans un format convivial, y compris le symbole de devise approprié.

Pour en savoir plus sur les données renvoyées par l'API et comprendre ses limites, consultez Comprendre les données.

Expiration des rapports

Chaque rapport est automatiquement supprimé du service de l'API App Optimize 24 heures après sa création. Passé ce délai, il ne sera plus possible de récupérer le rapport et ses données via l'API. Pour vérifier l'heure d'expiration planifiée d'un rapport, obtenez ses métadonnées et consultez le champ expireTime.