Berichte

Vorschau

Dieses Produkt unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Wenn Sie Kosten- und Nutzungsdaten mit der App Optimize API abrufen möchten, müssen Sie zuerst einen Bericht erstellen. Diese Ressource dient als dauerhafte Definition für die Daten, die Sie analysieren möchten. Sie enthält Parameter wie den Bereich, die Dimensionen, den Zeitraum und die Filter.

Nachdem Sie einen Bericht erstellt haben, werden die angeforderten Daten von der API asynchron generiert. Anschließend verwenden Sie den Ressourcennamen des Berichts, um das resultierende Dataset abzurufen.

Der Workflow sieht also so aus:

1. Sie erstellen einen Bericht und geben Ihre Kriterien an.
2. Das System verarbeitet diese Anfrage asynchron.
3. Wenn der Vorgang abgeschlossen ist, lesen Sie die Ergebnisdaten.

In diesem Dokument werden die Struktur und die konfigurierbaren Parameter von App Optimize API-Berichten beschrieben, einschließlich der verfügbaren Dimensionen, Messwerte und Filteroptionen. Außerdem wird das Format der zurückgegebenen Daten erläutert.

Informationen zu Einschränkungen bei Kosten und Nutzung finden Sie unter Daten verstehen.

Bericht definieren

Wenn Sie einen Bericht erstellen möchten, definieren Sie eine Report-Ressource mit den folgenden Konfigurationsparametern, die in den nächsten Unterabschnitten beschrieben werden:

Parameter	Typ	Beschreibung
scopes	Array	Das zu analysierende Projekt oder die zu analysierende App Hub-Anwendung. Sie müssen genau ein „scope“-Element angeben.
dimensions	Array	Die Attribute, nach denen die Daten abgerufen und gruppiert werden sollen, einschließlich zeitbasierter Gruppierungen.
metrics	Array	Die spezifischen Messungen, die zurückgegeben werden sollen.
filter	String	Ein CEL-Ausdruck (Common Expression Language), um die Daten einzugrenzen, einschließlich Zeiträumen.

Bereiche

Das Feld scopes definiert die Gruppe von Ressourcen, die von der App Optimize API analysiert werden. Obwohl das Feld ein Array ist, müssen Sie genau ein Element angeben, das entweder ein Projekt oder eine App Hub-Anwendung sein kann:

• project: Ein String, der ein Google Cloud Projekt darstellt. Es muss so formatiert sein:

  projects/PROJECT_ID
  

  Ersetzen Sie PROJECT_ID durch die ID Ihres Projekts von Google Cloud . Beispiel: projects/my-project-1

• application: Ein String, der den vollständigen Ressourcennamen einer App Hub-Anwendung darstellt. Sie muss so formatiert sein:

  projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
  

  Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID des App Hub-Hostprojekts.
  • LOCATION: Die Region der App Hub-Anwendung, z. B. us-central1.
  • APPLICATION_ID: die ID der App Hub-Anwendung.

  Beispiel: projects/my-host-proj/locations/us-central1/applications/my-app.

Hier sind Beispiel-scopes-Arrays in JSON für eine Anfrage zum Erstellen eines Berichts mit einem einzelnen Bereichselement:

• Umfang nach Projekt:

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

• Bereich nach Anwendung festlegen:

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

Dimensionen

Mit Dimensionen wird festgelegt, welche Daten zurückgegeben werden und wie die Daten gruppiert werden. Wenn Sie beispielsweise project und product_display_name auswählen, enthält die Ausgabe eine Zeile für jede eindeutige Kombination von Projekt- und Produktnamenwerten in den Daten.

Hier ist eine Tabelle der unterstützten Dimensionen:

Dimension	Typ	Beschreibung	Beispielwert
project	STRING	Die Google Cloud Projekt-ID.	projects/my-project
application	STRING	Die App Hub-Anwendung.	projects/my-project/locations/us-central1/applications/my-app
service_or_workload	STRING	Der App Hub-Dienst oder die App Hub-Arbeitslast.	projects/my-project/locations/us-central1/applications/my-app/services/my-service
resource	STRING	Der vollständige Ressourcenname.	//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1
resource_type	STRING	Der API-Ressourcentyp.	compute.googleapis.com/Instance
location	STRING	Die Google Cloud -Region oder Multiregion.	us-east1
sku	STRING	Die ID der Abrechnungs-SKU.	4496-8C0D-228F
product_display_name	STRING	Der Google Cloud Produktname.	Compute Engine
month	STRING	Das Jahr und der Monat.	2024-01
day	STRING	Das Jahr, der Monat und der Tag.	2024-01-10
hour	STRING	Jahr, Monat, Tag und Stunde.	2024-01-10T00

Die Dimension location stellt die Google Cloud Region oder Multiregion dar, der Kosten und Nutzung zugeordnet werden. Wie dieser Standort gemeldet wird, hängt von den Standorteinstellungen der Ressourcen im Berichtsbereich ab:

• Bei Ressourcen, die in einer bestimmten Zone bereitgestellt werden, z. B. us-central1-a, werden die Kosten und die Nutzung aggregiert und der übergeordneten Region zugeordnet. In diesem Beispiel würde für die Dimension location der Wert us-central1 angezeigt.
• Bei Ressourcen, die in einer Region bereitgestellt werden, z. B. us-central1, spiegelt die Dimension location diese bestimmte Region wider.
• Bei Ressourcen, die für eine Multi-Region wie us bereitgestellt oder konfiguriert werden, spiegelt die Dimension location diese Multi-Region wider.

Zeitdimensionen

Wenn Sie die Ergebnisse nach Zeit zusammenfassen möchten, müssen Sie mindestens eine Zeitdimension wie month, day oder hour in die Liste dimensions aufnehmen. Beachten Sie Folgendes:

• Für alle Zeitdimensionen wird Pacific Time verwendet und die Sommerzeit berücksichtigt.
• Die Formate entsprechen ISO 8601.
• Wenn der Zeitraum in filter nicht genau mit der Granularität der ausgewählten Zeitdimension übereinstimmt, wird der Zeitraum erweitert, um die vollständigen Zeiträume abzudecken. Wenn Sie beispielsweise mit dimension: ["month"] nach einem Teil eines Tages filtern, werden Daten für den gesamten Monat berücksichtigt.

Messwerte

Messwerte sind die quantitativen Werte, die Sie für jede Gruppe messen möchten, die durch Ihre Dimensionen definiert wird. Folgende Messwerte werden unterstützt:

Messwert	Typ	Beschreibung
cost	RECORD	Die Kosten in der angeforderten Währung.
cpu_mean_utilization	FLOAT64	Durchschnittliche CPU-Auslastung (0,0 bis 1,0).
cpu_p95_utilization	FLOAT64	CPU-Auslastung im 95. Perzentil (0,0 bis 1,0).
cpu_usage_core_seconds	INT64	Insgesamt ausgeführte CPU-Arbeit.
cpu_allocation_core_seconds	INT64	Insgesamt bereitgestellte CPU-Kapazität.
memory_mean_utilization	FLOAT64	Durchschnittliche Arbeitsspeicherauslastung (0,0 bis 1,0).
memory_p95_utilization	FLOAT64	Arbeitsspeicherauslastung im 95. Perzentil (0,0 bis 1,0).
memory_usage_byte_seconds	INT64	Insgesamt verwendeter Arbeitsspeicher im Zeitverlauf.
memory_allocation_byte_seconds	INT64	Insgesamt bereitgestellter Arbeitsspeicher im Zeitverlauf.

Gültige Kombinationen

Nicht alle Dimensionen können mit jedem Messwert in der App Optimize API kombiniert werden. Die folgende Tabelle enthält Beispiele für gültige Dimensionsgruppen und die Messwerte, die Sie damit verwenden können. Die API gibt einen Fehler zurück, wenn eine ungültige Kombination angefordert wird. Informationen zu gültigen Kombinationen finden Sie in der Fehlermeldung.

Dimensionen	Unterstützt den Messwert cost	Unterstützt den Messwert 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

Filter

Mit dem Feld filter können Sie die Daten mithilfe eines CEL-Strings eingrenzen. Sie können Filterausdrücke mit allen Feldern erstellen, die in der Tabelle Dimensionen aufgeführt sind.

Beim Filtern müssen folgende Einschränkungen beachtet werden:

• Für alle Stringfeld-Vorhersagen muss die genaue Stringübereinstimmung verwendet werden. Beispiel: location == 'us-east1'.
• Mehrere Prädikate, die sich auf dasselbe Stringfeld beziehen, müssen mit dem logischen ODER-Operator || verknüpft werden. Beispiel: location == 'us-east1' || location == 'us-west1'.
• Alle anderen Prädikate müssen mit dem logischen AND-Operator && verknüpft werden.
• Für ein Prädikat für eine Zeitdimension, z. B. day, mit dem die Startzeit angegeben wird, muss der Vergleich „größer als oder gleich“ (>=) verwendet werden.
• Für ein Prädikat für eine Zeitdimension, in dem die Endzeit angegeben wird, muss der Vergleich „kleiner als“ (<) verwendet werden.

Zeitraum

Wenn im filter Zeitdimensionen (month, day, hour) fehlen, wird im Bericht standardmäßig ein Zeitraum von sieben Tagen verwendet, der am vorherigen Mitternacht (Pazifische Zeit) endet. Die Sommerzeit wird dabei berücksichtigt. Der Zeitraum darf maximal 90 Tage vor dem aktuellen Datum liegen und die Startzeit muss innerhalb des 90‑Tage-Zeitfensters liegen.

Wenn die aktuelle Pacific Time beispielsweise 2026-01-05T12:00:00 ist, ist der Standardbereich 2025-12-29T00:00:00 bis 2026-01-05T00:00:00 Pacific Time. Die früheste Startzeit für den Zeitraum ist 2025-10-07T00:00:00.

Cloud Run-Messwerte sind nur für sechs Wochen vor dem aktuellen Datum verfügbar.

Beispielfilter

Hier sind einige Beispiele für die Strukturierung Ihrer CEL-Filterstrings:

• Wenn Sie die Berichtsdaten nach einem bestimmten Ressourcentyp filtern möchten, verwenden Sie den Operator == für die Dimension resource_type:

  resource_type == 'compute.googleapis.com/Instance'
  

• Wenn Sie nur Daten von einem einzelnen Standort einbeziehen möchten, filtern Sie nach der Dimension location:

  location == 'us-east1'
  

• Wenn Sie Daten aus einer bestimmten Liste von Standorten einbeziehen möchten, verwenden Sie den Operator ||, um Bedingungen für die Dimension location zu kombinieren:

  location == 'us-east1' || location == 'us-west1'
  

• Wenn Sie Daten in einem bestimmten Zeitraum mit stündlicher Granularität abrufen möchten, können Sie nach der Dimension hour filtern. Dieses Beispiel enthält Daten vom 01.01.2024 bis zum 01.02.2024 (ausschließlich):

  hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
  

• Wenn Sie nach ganzen Tagen filtern möchten, verwenden Sie die Dimension day. Tagesgrenzen werden in Pacific Time interpretiert. Es empfiehlt sich daher, den Offset anzugeben. Dieses Beispiel enthält alle Daten für den 15.03.2024 und den 16.03.2024:

  day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
  

• Sie können auch nach Kalendermonaten filtern. Verwenden Sie dazu die Dimension month. Achten Sie dabei auf die genauen Grenzen in Pacific Time. Dieses Beispiel enthält alle Daten für Oktober und November 2025:

  month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
  

• Wenn Sie Daten aus den letzten 72 Stunden abrufen möchten, verwenden Sie die Funktionen now() und duration() für die Dimension hour:

  hour >= now() - duration('72h')
  

• Wenn Sie Daten der letzten sieben Tage abrufen möchten, können Sie duration() mit der Dimension hour verwenden:

  hour >= now() - duration('168h')
  

• Wenn Sie nach einem bestimmten Kalendermonat filtern möchten, z. B. nach dem vorherigen, müssen Sie die Start- und End-Zeitstempel in Ihrem Anwendungscode berechnen. Anschließend fügen Sie diese berechneten Zeitstempel in den CEL-Ausdruck ein. Konzeptionell könnte das so aussehen, wenn nach der Dimension day gefiltert wird:

  day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
  

  Ersetzen Sie Folgendes:

  • START_OF_LAST_MONTH: Der ISO 8601-Zeitstempelstring, der den Beginn des vorherigen Monats in der Zeitzone „Pacific Time“ darstellt, z. B. 2025-12-01T00:00:00-08:00.
  • START_OF_THIS_MONTH: Der ISO 8601-Zeitstempelstring, der den Beginn des aktuellen Monats in der Zeitzone „Pacific Time“ darstellt, z. B. 2026-01-01T00:00:00-08:00.

  Sie müssen diese genauen Zeitstempelstrings in Ihrem Anwendungscode berechnen und dabei das aktuelle Datum, die Zeitzone (Pacific Time) und die Umstellung auf die Sommerzeit berücksichtigen.

• Sie können String- und Zeitfilter mit dem Operator && kombinieren. In diesem Beispiel wird nach zwei Standorten in einem bestimmten zweimonatigen Zeitraum gefiltert:

  (location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
  

• Hier ein komplexeres Beispiel, in dem resource_type, project und ein day-basierter Zeitraum kombiniert werden:

  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')
  

Datenstruktur des Berichts

Wenn Sie einen Bericht erfolgreich lesen, gibt der Dienst die Daten als columns und rows zurück.

Spalten

Das Array columns beschreibt das Schema der Daten in der Reihenfolge, in der die einzelnen Felder in rows angezeigt werden. Jedes Objekt im columns-Array hat ein name, ein type und manchmal ein verschachteltes columns, wenn der Typ RECORD ist.

• Die von Ihnen angeforderten Dimensionen werden als Felder mit dem Typ STRING angezeigt.
• Die angeforderten Messwerte werden als Felder mit Typen wie INT64, FLOAT64 oder RECORD für komplexe Typen wie cost angezeigt.

Wenn Sie beispielsweise mit der REST API dimensions: ["application", "product_display_name"] und metrics: ["cost", "cpu_mean_utilization"] anfordern, generiert die App Optimize API als Antwort ein columns-Array wie dieses:

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

Zeilen

Das Feld rows enthält die tatsächlichen Daten. Jede Zeile ist ein Array von Werten, das einen einzelnen Datensatz darstellt. Die Reihenfolge der Werte in jedem inneren Array entspricht direkt der Reihenfolge der Felder, die im columns-Array definiert sind.

Wenn wir das Beispiel fortsetzen, in dem application, product_display_name, cost und cpu_mean_utilization über die REST API angefordert wurden, könnte eine einzelne Zeile im generierten rows-Array so aussehen:

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

In der folgenden Tabelle sehen Sie, wie die Werte in einem einzelnen Zeilenarray dem im columns-Array definierten Schema zugeordnet werden. Dabei wird der Index des Werts im Zeilenarray verwendet:

Index innerhalb der Zeile	Entsprechende Spalte	Typ	Beispielwert
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

Jedes Element in der Liste rows ist ein Array, in dem die Reihenfolge der Werte der Reihenfolge der Felddefinitionen im Array columns entspricht. Der Wert am Index n in einem beliebigen Zeilenarray entspricht also der Spalte, die am Index n im Array columns definiert ist.

Kostenmesswerte interpretieren

Wenn ein Bericht den Messwert cost enthält, wird der Wert als RECORD zurückgegeben, das die folgenden Felder basierend auf dem Standardtyp google.type.Money enthält:

Feld	Typ	Beschreibung
currency_code	STRING	Der aus drei Buchstaben bestehende Währungscode gemäß ISO 4217, z. B. „EUR“.
units	INT64	Die ganzen Einheiten des Betrags.
nanos	INT64	Die Nanoeinheiten (10^-9) des Betrags. Der Wert muss im Bereich von -999.999.999 bis +999.999.999 liegen.

Um den vollständigen Geldwert zu erhalten, kombinieren Sie die Felder units und nanos. Das Feld nanos stellt den Bruchteil des Währungswerts dar. Beispiel:

• Wenn currency_code „USD“ ist, units 106 und nanos 321590000 ist: Der Wert ist 106 + (321.590.000 / 1.000.000.000) = 106,32159 $.

• Wenn currency_code „EUR“ ist, units 5 und nanos 750000000: Der Wert ist 5 + (750.000.000 / 1.000.000.000) = 5,75 €.

Normalerweise würden Sie eine Standardbibliothek für die Währungsformatierung verwenden, um diesen Wert in einem nutzerfreundlichen Format mit dem entsprechenden Währungssymbol darzustellen.

Weitere Informationen zu den von der API zurückgegebenen Daten und ihren Einschränkungen finden Sie unter Daten verstehen.

Ablauf von Berichten

Jeder Bericht wird 24 Stunden nach seiner Erstellung automatisch aus dem App Optimize API-Dienst gelöscht. Danach können der Bericht und seine Daten nicht mehr über die API abgerufen werden. Wenn Sie den geplanten Ablauf eines Berichts prüfen möchten, rufen Sie seine Metadaten ab und sehen Sie sich das Feld expireTime an.

Nächste Schritte

• Bericht erstellen
• Berichte auflisten
• Metadaten eines Berichts abrufen
• Berichtsdaten lesen
• Bericht löschen