Informazioni sui report

Per recuperare i dati su costi e utilizzo con l'API App Optimize, devi prima creare un report. Questa risorsa funge da definizione persistente per i dati che vuoi analizzare, specificando parametri come ambito, dimensioni, intervallo di tempo e filtri.

Dopo aver creato un report, l'API genera i dati richiesti in modo asincrono. Successivamente, utilizzi il nome della risorsa del report per recuperare il set di dati risultante.

Il flusso di lavoro è quindi il seguente:

Crea un report specificando i tuoi criteri.
Il sistema elabora questa richiesta in modo asincrono.
Al termine dell'operazione, leggi i dati risultanti.

Questo documento descrive in dettaglio la struttura e i parametri configurabili dei report dell'API App Optimize, incluse le dimensioni, le metriche e le opzioni di filtro disponibili, e spiega il formato dei dati restituiti.

Per informazioni sulle limitazioni relative a costi e utilizzo, consulta Comprendere i dati.

Definire un report

Per creare un report, definisci una risorsa Report con i seguenti parametri di configurazione, descritti nelle sottosezioni successive:

Parametro	Tipo	Descrizione
`scopes`	Array	Il progetto o l'applicazione App Hub da analizzare. Devi fornire esattamente un elemento scope.
`dimensions`	Array	Gli attributi in base ai quali recuperare e raggruppare i dati, inclusi i raggruppamenti basati sul tempo.
`metrics`	Array	Le misurazioni specifiche da restituire.
`filter`	Stringa	Un'espressione Common Expression Language (CEL) per restringere i dati, inclusi gli intervalli di tempo.

Ambiti

Il campo scopes definisce l'insieme di risorse che l'API App Optimize analizzerà. Sebbene il campo sia un array, devi specificare esattamente un elemento, che può essere un progetto o un'applicazione App Hub:

project: una stringa che rappresenta un Google Cloud progetto. Deve essere formattato come:
```
projects/PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud . Ad esempio: projects/my-project-1.
application: una stringa che rappresenta il nome completo della risorsa di un'applicazione App Hub. Deve essere formattato come segue:
```
projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto host App Hub.
- LOCATION: la regione dell'applicazione App Hub, ad esempio us-central1.
- APPLICATION_ID: l'ID dell'applicazione App Hub.
Ad esempio, projects/my-host-proj/locations/us-central1/applications/my-app.

Ecco alcuni esempi di array scopes in formato JSON per una richiesta di creazione di report, che mostrano un singolo elemento di ambito:

Definizione dell'ambito per progetto:

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

Definizione dell'ambito per applicazione:

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

Dimensioni

Le dimensioni determinano i dati restituiti e la modalità di raggruppamento. Ad esempio, se selezioni project e product_display_name, l'output contiene una riga per ogni combinazione univoca di valori di nome del progetto e del prodotto trovata nei dati.

Ecco una tabella delle dimensioni supportate:

Dimensioni	Tipo	Descrizione	Valore di esempio
`project`	STRING	L'ID progetto Google Cloud .	`projects/my-project`
`application`	STRING	L'applicazione App Hub.	`projects/my-project/locations/us-central1/applications/my-app`
`service_or_workload`	STRING	Il servizio o il workload App Hub.	`projects/my-project/locations/us-central1/applications/my-app/services/my-service`
`resource`	STRING	Nome completo della risorsa.	`//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1`
`resource_type`	STRING	Il tipo di risorsa API.	`compute.googleapis.com/Instance`
`location`	STRING	La Google Cloud regione o multiregione.	`us-east1`
`sku`	STRING	L'ID SKU di fatturazione.	`4496-8C0D-228F`
`product_display_name`	STRING	Il Google Cloud nome del prodotto.	`Compute Engine`
`month`	STRING	L'anno e il mese.	`2024-01`
`day`	STRING	L'anno, il mese e il giorno.	`2024-01-10`
`hour`	STRING	Anno, mese, giorno e ora.	`2024-01-10T00`

La dimensione location rappresenta la regione o la multi-regione a cui sono attribuiti i costi e l'utilizzo. Google Cloud Il modo in cui viene segnalata questa località dipende dalle impostazioni di geolocalizzazione delle risorse nell'ambito del report:

Per le risorse di cui è stato eseguito il deployment in una zona specifica, ad esempio us-central1-a, i costi e l'utilizzo vengono aggregati e attribuiti alla regione principale. In questo esempio, la dimensione location mostrerà us-central1.
Per le risorse di cui è stato eseguito il deployment in una regione, ad esempio us-central1, la dimensione location riflette quella regione specifica.
Per le risorse di cui è stato eseguito il deployment o la configurazione per una multi-regione, ad esempio us, la dimensione location riflette quella multi-regione.

Dimensioni temporali

Per aggregare i risultati in base al tempo, includi almeno una dimensione temporale, ad esempio month, day o hour, nell'elenco dimensions. Tieni presente che:

Tutte le dimensioni temporali utilizzano l'ora del Pacifico e rispettano l'ora legale.
I formati seguono lo standard ISO 8601.
Se l'intervallo di tempo in filter non è perfettamente allineato alla granularità della dimensione temporale selezionata, l'intervallo viene espanso per coprire i periodi completi. Ad esempio, se filtri per una parte di un giorno con dimension: ["month"], verranno inclusi i dati dell'intero mese.

Metriche

Le metriche sono i valori quantitativi che vuoi misurare per ogni gruppo definito dalle dimensioni. Le metriche supportate sono:

Metrica	Tipo	Descrizione
`cost`	RECORD	Il costo monetario nella valuta richiesta.
`cpu_mean_utilization`	FLOAT64	Utilizzo CPU medio (da 0,0 a 1,0).
`cpu_p95_utilization`	FLOAT64	Utilizzo CPU del 95° percentile (da 0,0 a 1,0).
`cpu_usage_core_seconds`	INT64	Lavoro totale della CPU eseguito.
`cpu_allocation_core_seconds`	INT64	Capacità CPU totale sottoposta a provisioning.
`memory_mean_utilization`	FLOAT64	Utilizzo medio della memoria (da 0,0 a 1,0).
`memory_p95_utilization`	FLOAT64	Utilizzo della memoria del 95° percentile (da 0,0 a 1,0).
`memory_usage_byte_seconds`	INT64	Memoria totale utilizzata nel tempo.
`memory_allocation_byte_seconds`	INT64	Memoria totale di cui è stato eseguito il provisioning nel tempo.

Combinazioni valide

Non tutte le dimensioni possono essere combinate con ogni metrica nell'API App Optimize. La tabella seguente mostra esempi di set di dimensioni validi e le metriche che puoi utilizzare con questi set. L'API restituirà un errore se viene richiesta una combinazione non valida. Fai riferimento a questo errore per le combinazioni valide.

Dimensioni	Supporta la metrica `cost`	Supporta la metrica `cpu_mean_utilization`
`application`, `product_display_name`
`application`
`location`, `product_display_name`, `project`, `resource`, `resource_type`, `sku`
`location`, `product_display_name`, `project`, `resource`, `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`

Filtri

Utilizza il campo filter per restringere i dati utilizzando una stringa CEL. Puoi creare le espressioni di filtro utilizzando uno qualsiasi dei campi elencati nella tabella Dimensioni.

Il filtraggio deve rispettare i seguenti vincoli:

Tutti i predicati dei campi stringa devono utilizzare corrispondenze esatte delle stringhe. Ad esempio, location == 'us-east1'.
Più predicati che fanno riferimento allo stesso campo stringa devono essere uniti utilizzando l'operatore logico OR, ||. Ad esempio, location == 'us-east1' || location == 'us-west1'.
Tutti gli altri predicati devono essere uniti utilizzando l'operatore logico AND, &&.
Un predicato su una dimensione temporale, ad esempio day, che specifica l'ora di inizio deve utilizzare il confronto maggiore o uguale a, >=.
Un predicato su una dimensione temporale che specifica l'ora di fine deve utilizzare il confronto minore di, <.

Intervallo di tempo

Se filter omette le dimensioni temporali (month, day, hour), il report utilizza per impostazione predefinita un intervallo di sette giorni che termina a mezzanotte del giorno precedente del fuso orario del Pacifico, rispettando l'ora legale. L'intervallo di date massimo è 90 giorni prima della data attuale e l'ora di inizio deve rientrare nella finestra temporale di 90 giorni.

Ad esempio, se l'ora della costa occidentale degli Stati Uniti (PST) corrente è 2026-01-05T12:00:00, l'intervallo predefinito è dalle ore 2025-12-29T00:00:00 alle ore 2026-01-05T00:00:00 del fuso orario PST. L'ora di inizio più recente per l'intervallo di tempo è 2025-10-07T00:00:00.

Le metriche di Cloud Run sono disponibili solo per sei settimane prima della data attuale.

Filtri di esempio

Ecco alcuni esempi di come puoi strutturare le stringhe di filtro CEL:

Per filtrare i dati del report in base a un tipo di risorsa specifico, utilizza l'operatore == nella dimensione resource_type:
```
resource_type == 'compute.googleapis.com/Instance'
```
Per includere solo i dati di una singola località, filtra in base alla dimensione location:
```
location == 'us-east1'
```
Per includere i dati di un elenco specifico di località, utilizza l'operatore || per combinare le condizioni nella dimensione location:
```
location == 'us-east1' || location == 'us-west1'
```
Per ottenere dati in un intervallo di tempo specifico utilizzando la granularità oraria, puoi filtrare in base alla dimensione hour. Questo esempio include i dati dall'inizio del 2024-01-01 fino al 2024-02-01, escluso:
```
hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```
Per filtrare in base ai giorni interi, utilizza la dimensione day. Tieni presente che i limiti giornalieri vengono interpretati nel fuso orario del Pacifico, quindi specificare l'offset è una best practice. Questo esempio include tutti i dati per il 15/03/2024 e il 16/03/2024:
```
day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
```
Allo stesso modo, puoi filtrare per mesi di calendario utilizzando la dimensione month, tenendo sempre presente il fuso orario del Pacifico per i limiti esatti. Questo esempio include tutti i dati di ottobre e novembre 2025:
```
month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
```
Per ottenere i dati delle ultime 72 ore, utilizza le funzioni now() e duration() nella dimensione hour:
```
hour >= now() - duration('72h')
```
Per ottenere i dati degli ultimi sette giorni, puoi utilizzare duration() con la dimensione hour:
```
hour >= now() - duration('168h')
```
Il filtro per un mese di calendario specifico, come quello precedente, richiede il calcolo dei timestamp di inizio e fine nel codice dell'applicazione. Poi inserisci questi timestamp calcolati nell'espressione CEL. A livello concettuale, potrebbe avere il seguente aspetto, con l'applicazione di un filtro alla dimensione day:
```
day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
```
Sostituisci quanto segue:
- START_OF_LAST_MONTH: la stringa del timestamp ISO 8601 che rappresenta l'inizio del mese precedente nel fuso orario del Pacifico, ad esempio 2025-12-01T00:00:00-08:00.
- START_OF_THIS_MONTH: la stringa del timestamp ISO 8601 che rappresenta l'inizio del mese corrente nel fuso orario del Pacifico, ad esempio 2026-01-01T00:00:00-08:00.
Devi calcolare queste stringhe di timestamp esatte nel codice dell'applicazione, tenendo conto della data corrente, del fuso orario (Pacific Time) e delle transizioni dell'ora legale.
Puoi combinare i filtri per stringhe e ora utilizzando l'operatore &&. Questo esempio filtra in base a due località in un periodo di due mesi specifico:
```
(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```

Ecco un esempio più complesso che combina resource_type, project e un intervallo di tempo basato su 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')

Struttura dei dati del report

Quando leggi una segnalazione, il servizio restituisce i dati come columns e rows.

Colonne

L'array columns descrive lo schema dei dati, nell'ordine in cui ogni campo viene visualizzato in rows. Ogni oggetto nell'array columns ha un name, type e a volte un columns nidificato se il tipo è RECORD.

Le dimensioni che hai richiesto vengono visualizzate come campi di tipo STRING.
Le metriche che hai richiesto vengono visualizzate come campi con tipi come INT64, FLOAT64 o RECORD per tipi complessi come cost.

Ad esempio, con l'API REST, se richiedi dimensions: ["application", "product_display_name"] e metrics: ["cost", "cpu_mean_utilization"], l'API App Optimize in risposta genera un array columns come questo:

"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"
  }
]

Righe

Il campo rows contiene i dati effettivi. Ogni riga è un array di valori che rappresenta un singolo record. L'ordine dei valori all'interno di ogni array interno corrisponde direttamente all'ordine dei campi definiti nell'array columns.

Continuando l'esempio in cui application, product_display_name, cost e cpu_mean_utilization sono stati richiesti dall'API REST, una singola riga nell'array rows generato potrebbe avere questo aspetto:

"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
  ]
]

La seguente tabella mostra come i valori all'interno di una singola matrice di righe vengono mappati allo schema definito nella matrice columns, utilizzando l'indice del valore nella matrice di righe:

Indice all'interno della riga	Colonna corrispondente	Tipo	Valore di esempio
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`

Ogni elemento dell'elenco rows è un array in cui l'ordine dei valori corrisponde all'ordine delle definizioni dei campi nell'array columns. Pertanto, il valore all'indice n in qualsiasi array di righe corrisponde alla colonna definita all'indice n nell'array columns.

Interpretazione delle metriche relative ai costi

Quando un report include la metrica cost, il valore viene restituito come RECORD contenente i seguenti campi, in base al tipo google.type.Money standard:

Campo	Tipo	Descrizione
`currency_code`	STRING	Il codice di valuta ISO 4217 di tre lettere, ad esempio "USD".
`units`	INT64	Le unità intere dell'importo.
`nanos`	INT64	Le unità nano (10^-9) dell'importo. Deve essere compreso tra -999.999.999 e +999.999.999 inclusi.

Per ottenere il valore monetario completo, combina i campi units e nanos. Il campo nanos rappresenta la parte frazionaria del valore della valuta. Ad esempio:

Se currency_code è "USD", units è 106 e nanos è 321590000: Il valore è 106 + (321.590.000 / 1.000.000.000) = 106,32159 USD.
Se currency_code è "EUR", units è 5 e nanos è 750000000: Il valore è 5 + (750.000.000 / 1.000.000.000) = 5,75 EUR.

In genere, utilizzeresti una libreria di formattazione standard per visualizzare questo valore in un formato intuitivo, incluso il simbolo della valuta appropriato.

Per ulteriori informazioni sui dati restituiti dall'API e per comprenderne i limiti, consulta la sezione Comprendere i dati.

Scadenza del report

Ogni report viene eliminato automaticamente dal servizio API App Optimize 24 ore dopo la sua creazione. Trascorso questo periodo, il report e i relativi dati non possono essere recuperati tramite l'API. Per controllare l'ora di scadenza pianificata di un report, ottieni i relativi metadati e visualizza il campo expireTime.