Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מידע על דוחות

כדי לאחזר נתוני עלויות וניצול באמצעות App Optimize API, צריך קודם ליצור משאב report ב Google Cloud פרויקט לבחירתכם. המשאב הזה משמש כהגדרה קבועה של הנתונים שרוצים לנתח, ומצוינים בו פרמטרים כמו היקף, מאפיינים, טווח זמן ומסננים.

הפרויקט שבו מאוחסן הדוח לא צריך להיות המקור של נתוני הדוח. אפשר ליצור דוח בפרויקט אחד שמנתח נתונים מפרויקט מקור אחר או מאפליקציה של מרכז האפליקציות.

אחרי שיוצרים דוח, ה-API יוצר את הנתונים המבוקשים באופן אסינכרוני. אחר כך משתמשים בשם המשאב של הדוח כדי לאחזר את מערך הנתונים שמתקבל כשהדוח מוכן.

לכן תהליך העבודה הוא:

אתם יוצרים דוח ומציינים את הקריטריונים שלכם.
המערכת מעבדת את הבקשה הזו באופן אסינכרוני.
בסיום הפעולה, קוראים את הנתונים שהתקבלו.

במסמך הזה מפורטים המבנה והפרמטרים שאפשר להגדיר בדוחות של App Optimize API, כולל המאפיינים, המדדים ואפשרויות הסינון שזמינים, ומוסבר הפורמט של הנתונים שמוחזרים.

מידע על מגבלות בנוגע לעלויות ולשימוש מופיע במאמר הסבר על הנתונים.

הגדרת דוח

כדי ליצור דוח, מגדירים Report משאב עם פרמטרי ההגדרה הבאים, שמתוארים בקטעי המשנה הבאים:

פרמטר	סוג	תיאור
`scopes`	מערך	הפרויקט או האפליקציה ב-מרכז האפליקציות שרוצים לנתח. חובה לציין רכיב היקף אחד בדיוק.
`dimensions`	מערך	המאפיינים שבהם רוצים לאחזר את הנתונים ולקבץ אותם, כולל קיבוצים לפי זמן.
`metrics`	מערך	המדידות הספציפיות שיוחזרו.
`filter`	String	ביטוי Common Expression Language ‏ (CEL) לצמצום הנתונים, כולל טווחי זמן.

היקפים

השדה scopes מגדיר את קבוצת המשאבים ש-App Optimize API ינתח. למרות שהשדה הוא מערך, צריך לציין בו בדיוק רכיב אחד, שיכול להיות פרויקט או אפליקציה ב-מרכז האפליקציות:

‫project: מחרוזת שמייצגת Google Cloud פרויקט. הפורמט צריך להיות:
```
projects/PROJECT_ID
```
מחליפים את PROJECT_ID במזהה של הפרויקט שרוצים לנתח. Google Cloud לדוגמה, projects/my-project-1.
‫application: מחרוזת שמייצגת את שם המשאב המלא של אפליקציית מרכז האפליקציות. הפורמט צריך להיות:
```
projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫PROJECT_ID: המזהה של פרויקט המארח של מרכז האפליקציות.
- ‫LOCATION: האזור של אפליקציית מרכז האפליקציות, למשל us-central1.
- ‫APPLICATION_ID: המזהה של אפליקציית מרכז האפליקציות.
לדוגמה, projects/my-host-proj/locations/us-central1/applications/my-app.

דוגמאות למערכי scopes ב-JSON לבקשת יצירת דוח, שכוללות רכיב היקף יחיד:

הגדרת היקף לפי פרויקט:

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

הגדרת היקף לפי אפליקציה:

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

מידות

המאפיינים קובעים אילו נתונים יוחזרו ואיך הנתונים יקובצו. לדוגמה, אם בוחרים בערכים project ו-product_display_name, הפלט יכלול שורה אחת לכל שילוב ייחודי של ערכי שם הפרויקט ושם המוצר שנמצאו בנתונים.

טבלה של מאפיינים נתמכים:

מאפיין	סוג	תיאור	ערך לדוגמה
`project`	מחרוזת	מזהה הפרויקט Google Cloud .	`projects/my-project`
`application`	מחרוזת	אפליקציית מרכז האפליקציות.	`projects/my-project/locations/us-central1/applications/my-app`
`service_or_workload`	מחרוזת	עומס העבודה או השירות של מרכז האפליקציות.	`projects/my-project/locations/us-central1/applications/my-app/services/my-service`
`resource`	מחרוזת	השם המלא של המשאב.	`//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1`
`resource_type`	מחרוזת	סוג המשאב ב-API.	`compute.googleapis.com/Instance`
`location`	מחרוזת	Google Cloud האזור או מספר האזורים.	`us-east1`
`sku`	מחרוזת	המק"ט לחיוב.	`4496-8C0D-228F`
`product_display_name`	מחרוזת	Google Cloud שם המוצר.	`Compute Engine`
`month`	מחרוזת	השנה והחודש.	`2024-01`
`day`	מחרוזת	השנה, החודש והיום.	`2024-01-10`
`hour`	מחרוזת	השנה, החודש, היום והשעה.	`2024-01-10T00`

המאפיין location מייצג את האזור או מספר האזורים שאליהם משויכות העלויות והשימוש. Google Cloud אופן הדיווח על המיקום הזה תלוי בהגדרות המיקום של המשאבים בהיקף הדוח:

למשאבים שפריסתם מתבצעת באזור ספציפי, כמו us-central1-a, העלויות והשימוש מצטברים ומשויכים לאזור האב. בדוגמה הזו, במאפיין location יוצג הערך us-central1.
למשאבים שנפרסו באזור מסוים, כמו us-central1, המאפיין location משקף את האזור הספציפי הזה.
למשאבים שנפרסו או הוגדרו למספר אזורים, כמו us, המימד location משקף את מספר האזורים האלה.

מאפייני זמן

כדי לצבור תוצאות לפי זמן, צריך לכלול ברשימה dimensions לפחות מאפיין אחד שקשור לזמן, כמו month, day או hour. חשוב לזכור:

כל מאפייני הזמן הם לפי שעון החוף המערבי בארה"ב ומשתנים בהתאם לשעון הקיץ.
הפורמטים הם לפי ISO 8601.
אם טווח הזמן בfilter לא תואם בדיוק לגרנולריות של מאפיין הזמן שנבחר, הטווח יורחב כך שיכלול את כל התקופות. לדוגמה, סינון של חלק מהיום באמצעות dimension: ["month"] יכלול נתונים של החודש כולו.

מדדים

מדדים הם הערכים הכמותיים שרוצים למדוד עבור כל קבוצה שהוגדרה על ידי המאפיינים. המדדים הנתמכים הם:

מדד	סוג	תיאור
`cost`	רשומה	העלות הכספית במטבע המבוקש.
`cpu_mean_utilization`	FLOAT64	ממוצע ניצול המעבד (0.0 עד 1.0).
`cpu_p95_utilization`	FLOAT64	אחוזון 95 של ניצול המעבד (0.0 עד 1.0).
`cpu_usage_core_seconds`	INT64	סך העבודה שבוצעה על ידי המעבד.
`cpu_allocation_core_seconds`	INT64	הקיבולת הכוללת של יחידת העיבוד המרכזית שהוקצתה.
`memory_mean_utilization`	FLOAT64	ממוצע ניצול הזיכרון (0.0 עד 1.0).
`memory_p95_utilization`	FLOAT64	ניצול הזיכרון במאיון ה-95 (0.0 עד 1.0).
`memory_usage_byte_seconds`	INT64	הזיכרון הכולל שבו נעשה שימוש לאורך זמן.
`memory_allocation_byte_seconds`	INT64	הנפח הכולל של הזיכרון שהוקצה לאורך זמן.

שילובים תקינים

אי אפשר לשלב כל מאפיין עם כל מדד ב-App Optimize API. בטבלה הבאה מוצגות דוגמאות לקבוצות מאפיינים תקינות ולמדדים שאפשר להשתמש בהם. אם תתבקש שילוב לא תקין, ה-API יחזיר שגיאה. השגיאה תציין את השילובים התקינים.

מידות	תמיכה במדד `cost`	תמיכה במדד `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 כדי לצמצם את הנתונים באמצעות מחרוזת CEL. אפשר ליצור ביטויי מסנן באמצעות כל אחד מהשדות שמפורטים בטבלה Dimensions.

הסינון צריך לעמוד במגבלות הבאות:

כל פרדיקטים של שדות מחרוזת חייבים להשתמש בהתאמות מדויקות של מחרוזות. לדוגמה, location == 'us-east1'.
אם יש כמה פרדיקטים שמתייחסים לאותו שדה מחרוזת, צריך לצרף אותם באמצעות האופרטור הלוגי OR,‏ ||. לדוגמה, location == 'us-east1' || location == 'us-west1'.
כל שאר הפרדיקטים צריכים להיות מחוברים באמצעות האופרטור הלוגי AND, ‏ &&.
בפרדיקט של מאפיין זמן, כמו day, שבו מציינים את שעת ההתחלה, צריך להשתמש בהשוואה 'גדול או שווה ל', >=.
בפרדיקט של מאפיין זמן שבו מצוין זמן הסיום, צריך להשתמש בהשוואה 'קטן מ', <.

טווח תאריכים

אם בדוח filter לא מופיעים מאפייני זמן (month, day, hour), טווח התאריכים שיוצג בדוח יהיה ברירת המחדל של שבעה ימים, עד חצות שעון פסיפיק של היום הקודם, בהתאם לשעון הקיץ. טווח התאריכים המקסימלי הוא 90 ימים לפני התאריך הנוכחי, ותאריך ההתחלה חייב להיות בטווח של 90 הימים.

לדוגמה, אם השעה הנוכחית לפי שעון החוף המערבי היא 2026-01-05T12:00:00, טווח ברירת המחדל הוא 2025-12-29T00:00:00 עד 2026-01-05T00:00:00 לפי שעון החוף המערבי. שעת ההתחלה המוקדמת ביותר של טווח הזמן היא 2025-10-07T00:00:00.

מדדים של Cloud Run זמינים רק לשישה שבועות לפני התאריך הנוכחי.

דוגמאות למסננים

הנה כמה דוגמאות למבנה של מחרוזות מסננים ב-CEL:

כדי לסנן את נתוני הדוח לפי סוג משאב ספציפי, משתמשים באופרטור == במאפיין resource_type:
```
resource_type == 'compute.googleapis.com/Instance'
```
כדי לכלול רק נתונים ממיקום יחיד, מסננים לפי location המאפיין:
```
location == 'us-east1'
```
כדי לכלול נתונים מרשימה ספציפית של מיקומים, משתמשים באופרטור || כדי לשלב תנאים במאפיין location:
```
location == 'us-east1' || location == 'us-west1'
```
כדי לקבל נתונים בטווח זמן ספציפי ברמת פירוט שעתית, אפשר לסנן לפי המאפיין hour. הדוגמה הזו כוללת נתונים מההתחלה של 2024-01-01 ועד 2024-02-01, לא כולל התאריך הזה:
```
hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```
כדי לסנן לפי ימים שלמים, משתמשים במימד day. שימו לב שהגבולות של הימים מפורשים לפי שעון החוף המערבי, ולכן מומלץ לציין את ההיסט. בדוגמה הזו נכללים כל הנתונים לתאריכים 15 במרץ 2024 ו-16 במרץ 2024:
```
day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
```
באופן דומה, אפשר לסנן לפי חודשים קלנדריים באמצעות המאפיין month, תוך הקפדה על גבולות מדויקים לפי שעון החוף הפסיפי. בדוגמה הזו נכללים כל הנתונים של אוקטובר ונובמבר 2025:
```
month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
```
כדי לקבל נתונים מ-72 השעות האחרונות, משתמשים בפונקציות now() ו-duration() במאפיין hour:
```
hour >= now() - duration('72h')
```
כדי לקבל נתונים מ-7 הימים האחרונים, אפשר להשתמש ב-duration() עם המאפיין hour:
```
hour >= now() - duration('168h')
```
כדי לסנן לפי חודש ספציפי ביומן, כמו החודש הקודם, צריך לחשב את חותמות הזמן של ההתחלה והסיום בקוד האפליקציה. אחר כך מוסיפים את חותמות הזמן המחושבות לביטוי CEL. מבחינה רעיונית, זה יכול להיראות כך, עם סינון לפי המימד day:
```
day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫START_OF_LAST_MONTH: מחרוזת חותמת הזמן בפורמט ISO 8601 שמייצגת את ההתחלה של החודש הקודם באזור הזמן של האוקיינוס השקט, למשל 2025-12-01T00:00:00-08:00.
- ‫START_OF_THIS_MONTH: מחרוזת חותמת הזמן בפורמט ISO 8601 שמייצגת את תחילת החודש הנוכחי באזור הזמן של האוקיינוס השקט, למשל 2026-01-01T00:00:00-08:00.
צריך לחשב את מחרוזות חותמות הזמן האלה בקוד האפליקציה, תוך התחשבות בתאריך הנוכחי, באזור הזמן (שעון החוף המערבי) ובמעברים לשעון קיץ.
אפשר לשלב בין מסנני מחרוזות ומסנני זמן באמצעות האופרטור &&. בדוגמה הזו, הסינון מתבצע לפי שני מיקומים בתקופה ספציפית של חודשיים:
```
(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```

דוגמה מורכבת יותר שמשלבת בין resource_type, project וטווח זמן שמבוסס על 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')

מבנה נתוני הדוח

כשקוראים דוח בהצלחה, השירות מחזיר את הנתונים כ-columns ו-rows.

Columns

המערך columns מתאר את סכימת הנתונים, לפי הסדר שבו כל שדה מופיע ב-rows. לכל אובייקט במערך columns יש name,‏ type ולפעמים columns מוטבע אם הסוג הוא RECORD.

המאפיינים שביקשתם מופיעים כשדות עם סוג STRING.
המדדים שביקשתם מופיעים כשדות עם סוגים כמו INT64,‏ FLOAT64 או RECORD לסוגים מורכבים כמו cost.

לדוגמה, אם משתמשים ב-API בארכיטקטורת REST ושולחים בקשה ל-dimensions: ["application", "product_display_name"] ול-metrics: ["cost", "cpu_mean_utilization"],‏ App Optimize API יפיק בתגובה מערך columns כזה:

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

Rows

השדה rows מכיל את הנתונים בפועל. כל שורה היא מערך של ערכים שמייצגים רשומה אחת. סדר הערכים בכל מערך פנימי תואם ישירות לסדר השדות שמוגדרים במערך columns.

בהמשך לדוגמה שבה נשלחה בקשה ל-API בארכיטקטורת REST עבור application, product_display_name, cost ו-cpu_mean_utilization, שורה אחת במערך rows שנוצר יכולה להיראות כך:

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

בטבלה הבאה מוצג מיפוי של הערכים במערך של שורה אחת לסכימה שמוגדרת במערך columns, באמצעות האינדקס של הערך במערך השורה:

אינדקס בתוך השורה	העמודה המתאימה	סוג	ערך לדוגמה
0	`application`	מחרוזת	`"//apphub.googleapis.com/.../applications/my-app"`
1	`product_display_name`	מחרוזת	`"Cloud Storage"`
2	`cost`	רשומה	`{ "currency_code": "USD", "units": "10", ... }`
3	`cpu_mean_utilization`	FLOAT64	`0.65`

כל רכיב ברשימה rows הוא מערך שבו סדר הערכים תואם לסדר ההגדרות של השדות במערך columns. לכן, הערך באינדקס n בכל מערך שורה נתון תואם לעמודה שמוגדרת באינדקס n במערך columns.

פירוש מדדי העלות

אם הדוח כולל את המדד cost, הערך שמוחזר הוא cost שכולל את השדות הבאים, על סמך הסוג הרגיל google.type.Money:RECORD

שדה	סוג	תיאור
`currency_code`	מחרוזת	קוד מטבע בן שלוש אותיות לפי תקן ISO 4217, למשל USD.
`units`	INT64	מספר היחידות השלמות של הסכום.
`nanos`	INT64	יחידות הננו (10^-9) של הסכום. הערך חייב להיות בין ‎-999,999,999 ל- ‎+999,999,999, כולל.

כדי לקבל את הערך הכספי המלא, משלבים את השדות units ו-nanos. השדה nanos מייצג את החלק השברי של ערך המטבע. לדוגמה:

אם currency_code הוא USD,‏ units הוא 106 ו-nanos הוא 321590000: הערך הוא ‎106 + (321,590,000 / 1,000,000,000) = 106.32159 USD‎.
אם currency_code הוא EUR,‏ units הוא 5 ו-nanos הוא 750000000: הערך הוא 5 + (‎750,000,000 / 1,000,000,000) = 5.75 EUR.

בדרך כלל משתמשים בספרייה רגילה לעיצוב מטבע כדי להציג את הערך הזה בפורמט ידידותי למשתמש, כולל סמל המטבע המתאים.

מידע נוסף על הנתונים שמוחזרים על ידי ה-API וההגבלות שלו זמין במאמר הסבר על הנתונים.

תוקף הדוח

כל דוח נמחק אוטומטית משירות App Optimize API‏ 24 שעות אחרי יצירת הדוח. אחרי התקופה הזו, אי אפשר לאחזר את הדוח והנתונים שלו דרך ה-API. כדי לבדוק את זמן התפוגה המתוזמן של דוח, צריך לקבל את המטא-נתונים שלו ולראות את השדה expireTime.