À propos des rapports

Aperçu

Ce produit est soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour récupérer les données de coût et d'utilisation avec l'API App Optimize, vous devez d'abord créer un rapport. Cette ressource sert de définition persistante pour les données que vous souhaitez analyser, en spécifiant des paramètres tels que le champ d'application, les dimensions, la plage de dates et les filtres.

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 obtenu.

Le workflow est donc le suivant :

1. Vous créez un rapport en spécifiant vos critères.
2. Le système traite cette requête de manière asynchrone.
3. 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 à récupérer et selon lesquels regrouper les données, y compris les regroupements basés sur le temps.
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 mis en forme comme suit :

  projects/PROJECT_ID
  

  Remplacez PROJECT_ID par l'ID de votre projet Google Cloud . 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 mis en forme comme suit :

  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 requête 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 nom 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 zone multirégionale Google Cloud .	us-east1
sku	STRING	ID du code 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 cet emplacement est indiqué dépend des paramètres géographiques des ressources incluses dans le champ d'application du rapport :

• Pour les ressources déployées dans une zone spécifique, telle que 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 (month, day ou hour, par exemple) dans la liste dimensions. N'oubliez pas :

• Toutes les dimensions temporelles utilisent l'heure du Pacifique et respectent l'heure d'été.
• Les formats suivent la norme ISO 8601.
• Si la période dans filter ne correspond pas parfaitement à la précision de la dimension temporelle sélectionnée, elle est élargie 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. Voici les métriques acceptées :

Métrique	Type	Description
cost	RECORD	Coût monétaire dans la devise demandée.
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 renvoie 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înes. Par exemple, location == 'us-east1'.
• Plusieurs prédicats faisant référence au même champ de chaîne doivent être associés à 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 plage de sept jours se terminant à minuit, heure du Pacifique, en tenant compte du passage à 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 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, heure 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 structuration de 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'à la période 2024-02-01 (non incluse) :

  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 pour le 15 et le 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. Voici à quoi cela pourrait ressembler, en filtrant 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 d'horodatage 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 d'horodatage 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 deux zones géographiques sur 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 dates 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 apparaissent 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, à l'aide de 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 de coût

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	Unités nano (10^-9) du montant. La valeur doit être comprise entre -999 999 999 et [phone] 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 "EUR", units est 5 et nanos est 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 du rapport

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.

Étapes suivantes

• Créer un rapport
• Lister les rapports
• Obtenir les métadonnées d'un rapport
• Lire les données d'un rapport
• Supprimer un rapport