Package google.api

אינדקס

• ‫Distribution (הודעה)
• ‫Distribution.BucketOptions (הודעה)
• ‫Distribution.BucketOptions.Explicit (הודעה)
• ‫Distribution.BucketOptions.Exponential (הודעה)
• ‫Distribution.BucketOptions.Linear (הודעה)
• ‫Distribution.Exemplar (הודעה)
• ‫Distribution.Range (הודעה)
• ‫HttpBody (הודעה)
• ‫Metric (הודעה)
• ‫MetricDescriptor (הודעה)
• MetricDescriptor.MetricKind (enum)
• MetricDescriptor.ValueType (enum)
• ‫MonitoredResource (הודעה)
• ‫MonitoredResourceMetadata (הודעה)

הפצה

‫Distribution מכיל נתונים סטטיסטיים מסכמים של אוכלוסיית ערכים. הוא יכול לכלול היסטוגרמה שמייצגת את ההתפלגות של הערכים האלה על פני קבוצה של קטגוריות.

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

למרות שאין איסור על כך, בדרך כלל לא מומלץ לכלול ערכים לא סופיים (אינסוף או NaN) באוכלוסיית הערכים, כי זה יגרום לכך שהשדות mean ו-sum_of_squared_deviation יהיו חסרי משמעות.

שדות
count	int64 מספר הערכים באוכלוסייה. הערך לא יכול להיות שלילי. אם מספקים היסטוגרמה, הערך הזה צריך להיות שווה לסכום הערכים ב-bucket_counts.
mean	double הממוצע החשבוני של הערכים באוכלוסייה. אם הערך של count הוא אפס, הערך בשדה הזה חייב להיות אפס.
sum_of_squared_deviation	double סכום הריבועים של הסטיות מהממוצע של הערכים באוכלוסייה. עבור הערכים x_i, זהו: Sum[i=1..n]((x_i - mean)^2) בספר Knuth, "The Art of Computer Programming", Vol. 2, page 232, 3rd edition מתואר השימוש בשיטה של Welford לצבירת הסכום הזה במעבר אחד. אם הערך של count הוא אפס, הערך בשדה הזה חייב להיות אפס.
range	Range אם מצוין, מכיל את טווח הערכים של האוכלוסייה. אם הערך של count הוא אפס, אסור להוסיף את השדה.
bucket_options	BucketOptions הגדרת גבולות של משבצות בהיסטוגרמה. אם ההתפלגות לא מכילה היסטוגרמה, צריך להשמיט את השדה הזה.
bucket_counts[]	int64 מספר הערכים בכל משבצת בהיסטוגרמה, כפי שמתואר בbucket_options. אם אין היסטוגרמה של ההתפלגות, אפשר להשמיט את השדה הזה. אם יש היסטוגרמה, סכום הערכים ב-bucket_counts צריך להיות שווה לערך בשדה count של ההתפלגות. אם המאפיין הזה קיים, הוא צריך להכיל N ערכים, כאשר N הוא מספר הדליים שצוין במאפיין bucket_options.bucket_counts אם תספקו פחות מ-N ערכים, הערכים הנותרים ייחשבו כ-0. הסדר של הערכים ב-bucket_counts תואם לשיטות המספור של הדליים שמתוארות בשלושת סוגי הדליים. הערך הראשון חייב להיות הספירה של קטגוריית הגלישה התחתונה (מספר 0). ‫N-2 הערכים הבאים הם הספירות של הדליים הסופיים (מספר 1 עד N-2). הערך ה-N ב-bucket_counts הוא הספירה של דלי הגלישה (מספר N-1).
exemplars[]	Exemplar הערכים צריכים להיות בסדר עולה של השדה value.

BucketOptions

‫BucketOptions מתאר את הגבולות של הקטגוריות שמשמשות ליצירת היסטוגרמה של ההתפלגות. הדליים יכולים להיות ברצף לינארי, ברצף אקספוננציאלי, או שכל דלי יכול להיות מוגדר באופן מפורש. הערך BucketOptions לא כולל את מספר הערכים בכל קבוצת משנה.

לכל קטגוריה יש גבול תחתון כולל וגבול עליון לא כולל של הערכים שנכללים בספירה של הקטגוריה. הגבול העליון של משבצת חייב להיות גדול מהגבול התחתון. הרצף של N קטגוריות לפי גודל להתפלגות כולל קטגוריה של ערכים נמוכים מדי (מספר 0), אפס או יותר קטגוריות של ערכים סופיים (מספר 1 עד N – 2) וקטגוריה של ערכים גבוהים מדי (מספר N – 1). הקטגוריות הן רציפות: הגבול התחתון של קטגוריה i (כאשר i > 0) זהה לגבול העליון של קטגוריה i - 1. הקטגוריות מכסות את כל טווח הערכים הסופיים: הגבול התחתון של קטגוריית הגלישה התחתונה הוא מינוס אינסוף, והגבול העליון של קטגוריית הגלישה העליונה הוא פלוס אינסוף. השם 'דליים סופיים' ניתן להם כי שני הגבולות שלהם סופיים.

שדות
שדה איחוד options. צריך להגדיר בדיוק אחד משלושת השדות האלה. הערך options יכול להיות רק אחד מהבאים:
linear_buckets	Linear הקטגוריה הלינארית.
exponential_buckets	Exponential הקטגוריות האקספוננציאליות.
explicit_buckets	Explicit הקטגוריות המפורשות.

מפורש

מגדיר קבוצה של דליים עם רוחב שרירותי.

יש size(bounds) + 1 (= N) קטגוריות. הגבולות של דלי i הם:

הגבול העליון (0 <= i < N-1): bounds[i] הגבול התחתון (1 <= i < N); bounds[i - 1]

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

שדות
bounds[]	double הערכים חייבים להיות בעלייה מונוטונית.

מעריכי

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

יש num_finite_buckets + 2 (= N) קטגוריות. הגבולות של דלי i הם:

הגבול העליון (0 <= i < N-1): scale * (growth_factor ^ i).

הגבול התחתון (‎1 <= i < N): ‏ scale * (growth_factor ^ (i - 1)).

שדות
num_finite_buckets	int32 הערך חייב להיות גדול מ-0.
growth_factor	double הערך חייב להיות גדול מ-1.
scale	double הערך חייב להיות גדול מ-0.

לינארי

מציין רצף לינארי של דליים שכולם באותו רוחב (חוץ מדליים של חריגה מעל וממתחת). כל דלי מייצג אי ודאות מוחלטת קבועה לגבי הערך הספציפי בדלי.

יש num_finite_buckets + 2 (= N) קטגוריות. הגבולות של דלי i הם:

הגבול העליון (‎0 <= i < N-1): offset + (width * i).

הגבול התחתון (‎1 <= i < N): offset + (width * (i - 1)).

שדות
num_finite_buckets	int32 הערך חייב להיות גדול מ-0.
width	double הערך חייב להיות גדול מ-0.
offset	double הגבול התחתון של הדלי הראשון.

דוגמה מייצגת

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

שדות
value	double הערך של נקודת המדגם. הערך הזה קובע לאיזה bucket שייך האקזמפלר.
timestamp	Timestamp זמן התצפית (הדגימה) של הערך שלמעלה.
attachments[]	Any מידע על ההקשר של ערך הדוגמה. לדוגמה: Trace: type.googleapis.com/google.monitoring.v3.SpanContext מחרוזת מילולית: type.googleapis.com/google.protobuf.StringValue תוויות שהוסרו במהלך הצבירה: type.googleapis.com/google.monitoring.v3.DroppedLabels יכול להיות רק קובץ מצורף אחד מכל סוג הודעה בדוגמה אחת, והמערכת אוכפת את זה.

טווח

הטווח של ערכי האוכלוסייה.

שדות
min	double הערך המינימלי של האוכלוסייה.
max	double הערך המקסימלי של האוכלוסייה.

HttpBody

הודעה שמייצגת גוף HTTP שרירותי. צריך להשתמש בו רק עבור פורמטים של מטען ייעודי (payload) שלא ניתן לייצג כ-JSON, כמו קובץ בינארי גולמי או דף HTML.

אפשר להשתמש בהודעה הזו גם בשיטות של API עם סטרימינג וגם בשיטות של API ללא סטרימינג, בבקשה וגם בתשובה.

אפשר להשתמש בו כשדה בקשה ברמה העליונה, וזה נוח אם רוצים לחלץ פרמטרים מתבנית של כתובת URL או HTTP לשדות הבקשה, וגם רוצים גישה לגוף ה-HTTP הגולמי.

דוגמה:

message GetResourceRequest {
  // A unique request id.
  string request_id = 1;

  // The raw HTTP body is bound to this field.
  google.api.HttpBody http_body = 2;

}

service ResourceService {
  rpc GetResource(GetResourceRequest)
    returns (google.api.HttpBody);
  rpc UpdateResource(google.api.HttpBody)
    returns (google.protobuf.Empty);

}

דוגמה לשימוש בשיטות סטרימינג:

service CaldavService {
  rpc GetCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);
  rpc UpdateCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);

}

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

שדות
content_type	string ערך הכותרת Content-Type של HTTP שמציין את סוג התוכן של הגוף.
data	bytes הגוף של בקשת ה-HTTP או התשובה כבינארי גולמי.
extensions[]	Any מטא-נתונים של תשובה ספציפית לאפליקציה. צריך להגדיר את הערך הזה בתשובה הראשונה ל-API של סטרימינג.

מדד

מדד ספציפי, שמזוהה על ידי ציון ערכים לכל התוויות של MetricDescriptor.

שדות
type	string סוג מדד קיים, ראו google.api.MetricDescriptor. לדוגמה, custom.googleapis.com/invoice/paid/amount.
labels	map<string, string> קבוצת ערכי התוויות שמזהים באופן ייחודי את המדד הזה. צריך להקצות ערכים לכל התוויות שמופיעות ב-MetricDescriptor.

MetricDescriptor

בסוג הזה אין שדות.

הגדרת סוג מדד והסכימה שלו. אחרי שיוצרים מתאר מדד, אם מוחקים אותו או משנים אותו, איסוף הנתונים נפסק והנתונים הקיימים של סוג המדד הופכים ללא שמישים.

MetricKind

סוג המדידה. היא מתארת את אופן הדיווח על הנתונים. למידע על הגדרת שעת ההתחלה ושעת הסיום על סמך MetricKind, ראו TimeInterval.

טיפוסים בני מנייה (enum)
METRIC_KIND_UNSPECIFIED	לא להשתמש בערך ברירת המחדל הזה.
GAUGE	מדידה מיידית של ערך.
DELTA	השינוי בערך במהלך מרווח זמן.
CUMULATIVE	ערך שנצבר לאורך מרווח זמן. למדידות מצטברות בסדרת זמן צריכות להיות אותה שעת התחלה ושעות סיום הולכות וגדלות, עד שאירוע מאפס את הערך המצטבר לאפס ומגדיר שעת התחלה חדשה לנקודות הבאות.

ValueType

סוג הערך של מדד.

טיפוסים בני מנייה (enum)
VALUE_TYPE_UNSPECIFIED	לא להשתמש בערך ברירת המחדל הזה.
BOOL	הערך הוא בוליאני. אפשר להשתמש בסוג הערך הזה רק אם סוג המדד הוא GAUGE.
INT64	הערך הוא מספר שלם עם סימן בגודל 64 ביט.
DOUBLE	הערך הוא מספר בשיטת נקודה צפה עם דיוק כפול.
STRING	הערך הוא מחרוזת טקסט. אפשר להשתמש בסוג הערך הזה רק אם סוג המדד הוא GAUGE.
DISTRIBUTION	הערך הוא Distribution.
MONEY	הערך הוא כסף.

MonitoredResource

אובייקט שמייצג משאב שאפשר להשתמש בו למעקב, לרישום ביומן, לחיוב או למטרות אחרות. לדוגמה, מכונות וירטואליות, מסדי נתונים ומכשירי אחסון כמו דיסקים. השדה type מזהה אובייקט MonitoredResourceDescriptor שמתאר את הסכימה של המשאב. המידע בשדה labels מזהה את המשאב בפועל ואת המאפיינים שלו בהתאם לסכימה. לדוגמה, מכונה וירטואלית מסוימת ב-Compute Engine יכולה להיות מיוצגת על ידי האובייקט הבא, כי ל-MonitoredResourceDescriptor של "gce_instance" יש תוויות "project_id", "instance_id" ו-"zone":

{ "type": "gce_instance",
  "labels": { "project_id": "my-project",
              "instance_id": "12345678901234",
              "zone": "us-central1-a" }}

שדות
type	string חובה. סוג המשאב במעקב. השדה הזה חייב להיות זהה לשדה type של אובייקט MonitoredResourceDescriptor. לדוגמה, הסוג של מכונה וירטואלית ב-Compute Engine הוא gce_instance. חלק מהמתארים כוללים את שם השירות בסוג; לדוגמה, הסוג של זרם Datastream הוא datastream.googleapis.com/Stream.
labels	map<string, string> חובה. ערכים לכל התוויות שמופיעות בתיאור המשאב במעקב המשויך. לדוגמה, מכונות וירטואליות של Compute Engine משתמשות בתוויות "project_id", "instance_id" ו-"zone".

MonitoredResourceMetadata

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

שדות
system_labels	Struct פלט בלבד. ערכים של תוויות מטא-נתונים מוגדרות מראש של המערכת. תוויות מערכת הן סוג של מטא-נתונים שמחולצים על ידי Google, כולל machine_image,‏ vpc,‏ subnet_id,‏ security_group,‏ name וכו'. הערכים של תוויות המערכת יכולים להיות רק מחרוזות, ערכים בוליאניים או רשימה של מחרוזות. לדוגמה: { "name": "my-test-instance", "security_group": ["a", "b", "c"], "spot_instance": false }
user_labels	map<string, string> פלט בלבד. מיפוי של תוויות מטא-נתונים שהוגדרו על ידי המשתמש.