שמירה או שיתוף של שאילתות SQL

אתם יכולים לשמור ולשתף שאילתות SQL ב-Observability Analytics, וכך להריץ מחדש חקירות שמתבצעות לעיתים קרובות ולשתף פעולה עם חברי הצוות בפרויקט. אפשר לשמור את השאילתות השמורות כך שיהיו פרטיות לשימושכם האישי, או לשתף אותן עם חברים אחרים בפרויקט. אם לא כתבתם שאילתות ב-Observability Analytics, כדאי קודם לעיין במאמר שאילתה וניתוח של טלמטריה באמצעות Observability Analytics.

לפני שמתחילים

מגדירים את הפרויקט ואת תפקידי ה-IAM ובוחרים את הממשק שבו רוצים להשתמש.

הגדרת הפרויקט והתפקידים

נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. כדי לקבל את ההרשאות שדרושות לטעינת הדף Observability Analytics, לכתיבה, להרצה ולשמירה של שאילתות פרטיות, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

   • Observability View Accessor (roles/observability.viewAccessor) בתצוגות הנתונים של יכולת התצפית שרוצים לשלוח להן שאילתות. התפקיד הזה תומך בתנאי IAM, שמאפשרים להגביל את ההרשאה לתצוגה ספציפית. אם לא מצרפים תנאי למתן התפקיד, לחשבון המשתמש תהיה גישה לכל תצוגות הנתונים של יכולת התצפית.
   • משתמש ב-Observability Analytics (roles/observability.analyticsUser) בפרויקט. התפקיד הזה כולל את ההרשאות שנדרשות כדי לשמור ולהריץ שאילתות פרטיות, ולהריץ שאילתות משותפות.
   • מציג היומנים (roles/logging.viewer) בפרויקט.
   • גישה לתצוגות של יומנים (roles/logging.viewAccessor) בפרויקט שבו מאוחסנות תצוגות היומנים שרוצים לשלוח אליהן שאילתות.

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

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

   הערה: אם רוצים ליצור ולנהל שאילתות משותפות, תפקידי ה-IAM הקודמים לא מספיקים. כדי ליצור ולנהל שאילתות משותפות, תפקידי ה-IAM שלכם צריכים לכלול את ההרשאות logging.queries.{share, updateShared, deleteShared}.

בחירת הממשק שבו רוצים להשתמש

המסוף

כשמשתמשים במסוף Google Cloud כדי לגשת לשירותים ולממשקי ה-API של Google Cloud , לא צריך להגדיר אימות.

gcloud

במסוף Google Cloud , מפעילים את Cloud Shell.

הפעלת Cloud Shell

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

REST

כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .

שמירת שאילתה

כל השאילתות שאתם מריצים נשמרות אוטומטית למשך 30 ימים, ואפשר לגשת אליהן דרך הכרטיסייה Recent בדף Observability Analytics. בכרטיסייה מהזמן האחרון אפשר לחפש, להציג, להריץ ולשתף את השאילתות שמופיעות בה.

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

אפשר לשמור 10,000 שאילתות בכל Google Cloud פרויקט.

הערה: שאילתות ששומרים באמצעות מסוף Google Cloud מאוחסנות במיקום global. כדי לציין איפה השאילתות מאוחסנות, משתמשים ב-Google Cloud CLI או ב-Cloud Logging API.

המסוף

כדי לשמור שאילתה:

1. נכנסים לדף Observability Analytics במסוף Google Cloud :

   עוברים אל Observability Analytics

   אם משתמשים בשורת החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.

2. ממלאים את החלונית Query בשאילתה.

   כדי לאכלס את החלונית Query, אפשר להזין שאילתה חדשה, לבחור שאילתה מהכרטיסייה Recent או לבחור שאילתה מהכרטיסייה Saved.

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

   אם השאילתה בחלונית שאילתה תקינה, הכפתור שמירה שמירה מופעל.

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

4. אופציונלי: כדי לאפשר לכל מי שיש לו גישה לדף Observability Analytics בתצוגת הפרויקט Google Cloud להציג ולהריץ את השאילתה השמורה, מפעילים את המתג Share with project.

   כברירת מחדל, המתג הזה מושבת וההרשאה מוגבלת אליכם.

5. לוחצים על שמירת השאילתה.

6. אופציונלי: כדי לראות, למיין ולהריץ שאילתות שמורות שגלויות לכם, בוחרים בכרטיסייה Saved.

   אפשר למיין ולסנן את השאילתות השמורות לפי השם, התיאור ותווית החשיפה שלהן. אפשר גם לסנן לפי תוכן השאילתה.

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

• כדי לערוך שאילתה, לוחצים על אפשרויות נוספות ובוחרים באפשרות עריכה. אפשר לשנות את הערכים בשדות Name ו-Description, אבל אי אפשר לשנות את השאילתה עצמה.

• כדי למחוק שאילתה שמורה, לוחצים על More Options ובוחרים באפשרות Delete.

gcloud

כדי ליצור ולשמור שאילתה:

1. לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

   • ‫DISPLAY_NAME: השם המוצג של השאילתה השמורה.
   • ‫LOCATION: המיקום של השאילתה השמורה.
   • ‫VISIBILITY: הערך צריך להיות private או shared.
   • ‫SQL_QUERY: שאילתת SQL. אם הנתיב או השדות בנתיב מוקפים בגרש הפוך בודד (`), צריך להוסיף תו בריחה לגרש ההפוך:

         "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"
         

     או

         "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"
         

     צריך להשתמש בגרש הפוך (`) כשרכיב נתיב מכיל תו נקודה (.).

   • ‫ID: המזהה של השאילתה השמורה. המזהה הזה הוא קלט חובה לפקודות שמתארות, מעדכנות או מוחקות שאילתה שמורה. אם לא מספקים את המזהה כשיוצרים שאילתה שמורה, המערכת יוצרת מזהה מספרי.
   • ‫DESCRIPTION: תיאור טקסטואלי של השאילתה. זה שינוי אופציונלי.
   • ‫PROJECT_ID: מזהה הפרויקט.

   מריצים את הפקודה gcloud logging saved-queries create:

   ‫Linux,‏ macOS או Cloud Shell

   gcloud logging saved-queries create --display-name=DISPLAY_NAME \
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   ‏Windows (PowerShell)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME `
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Windows‏ (cmd.exe)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   זו דוגמה לתשובה שמתקבלת כשהמזהה שצוין בפקודה הוא my-saved-query:

   Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].
   

   התשובה לפקודה create מפרטת את השם המלא של השאילתה, שכולל את מזהה השאילתה. מזהה השאילתה, שהוא my-saved-query בדוגמה הזו, הוא קלט חובה לפקודות Google Cloud CLI שמתארות, מוחקות או מעדכנות שאילתה שמורה.

2. כדי לבדוק את השאילתה השמורה, מריצים את הפקודה הבאה:

    gcloud logging saved-queries list --location=- --project=PROJECT_ID
   

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

יש פקודות Google Cloud CLI למחיקה, להצגה, לתיאור ולעדכון של שאילתות שמורות. מידע נוסף זמין במאמר סקירה כללית על gcloud logging saved-queries.

REST

אפשר לשמור שאילתה באמצעות Cloud Logging API. כדי לשמור שאילתה, משתמשים בשיטה savedQueries.create.

כדי להפעיל את השיטה הזו:

1. לוחצים על savedQueries.create.
2. בדף העזר, משתמשים ב-APIs Explorer כדי להנפיק פקודה. חובה לציין את השדה opsAnalyticsQuery.

בדוגמה הבאה מוצג גוף בקשה לדוגמה, שמכיל מופע של SavedQuery:

{
   "parent": "projects/my-project/locations/global"
   "saved_query":
   {
      "ops_analytics_query":
      {
         "sql_query_text" :
            "SELECT
            timestamp, log_name, severity, json_payload, resource, labels
            FROM
            `VIEW`
            WHERE
            timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
            ORDER BY timestamp ASC
            LIMIT 100"
      }
   "visibility": "PRIVATE"
   }
}

איך לשתף שאילתה

אתם יכולים לשתף שאילתה שמורה עם כל מי שיש לו גישה לפרויקט ב-Google Cloud . עם זאת, תפקידי ה-IAM של החשבון הראשי קובעים אם אפשר להריץ את השאילתה ואילו נתונים השאילתה מחזירה.

המסוף

כשפותרים בעיה או כשרואים תוצאות חריגות, יכול להיות שתרצו לשתף שאילתה ואת התוצאות שלה עם חבר צוות. כשצופים בתוצאות של שאילתה בדף Observability Analytics, אפשר להעתיק כתובת URL, וכשפותחים אותה, מוצגת השאילתה שהפעלתם והתוצאות שלה.

כדי לשתף שאילתה ותוצאות עם חבר צוות:

1. נכנסים לדף Observability Analytics במסוף Google Cloud :

   עוברים אל Observability Analytics

   אם משתמשים בשורת החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.

2. מאכלסים את החלונית Query בשאילתה ולוחצים על Run query.

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

3. לוחצים על שיתוף הקישור.

4. שולחים את הקישור לחבר הצוות.

   כשהקולגה יפתח את הקישור, הדף Observability Analytics ייפתח ותוצג בו השאילתה, אבל היא לא תופעל. החבר או החברה שלכם לצוות צריכים להריץ את השאילתה באופן ידני.

   בדף Observability Analytics מוצגת תיבת דו-שיח של אזהרה כשהשאילתה פועלת במנוע BigQuery והמשאבים ששלחתם אליהם שאילתה לא נמצאים באותו גבול בעלות. גבולות הבעלות נקבעים לפי כמה גורמים, שאחד מהם הוא ההיררכיה של המשאבים שבהם נעשה שימוש בשאילתה.

   כדי שכתובת ה-URL תיפתח בהצלחה, תפקיד ה-IAM של חבר הצוות ב Google Cloud פרויקט צריך לכלול את ההרשאות שנדרשות כדי להציג את הדף Observability Analytics.

gcloud

אם רוצים ליצור שאילתה שמורה שמשתמשים אחרים יכולים להריץ, צריך להגדיר את הערך של השדה visibility ל-shared:

--visibility=shared

כדי לשנות את ההגדרה של הניראות של שאילתה שמורה קיימת, משתמשים בפקודה update. למידע נוסף על הפקודות הזמינות, קראו את הסקירה הכללית על gcloud logging saved-queries.

REST

אפשר להשתמש ב-Logging API כדי ליצור שאילתה משותפת באמצעות ה-method‏ savedQueries.create, ולציין ערך של SHARED בשדה visibility. מידע נוסף זמין בדף העזרה בנושא savedQueries.create.

איך רואים ומריצים שאילתות אחרונות או שמורות

כדי לראות או להריץ מחדש שאילתה, בוחרים בכרטיסייה Recent בדף Observability Analytics ומחפשים את השאילתה:

• כדי להריץ את השאילתה, לוחצים על Run.
• כדי לראות את השאילתה, משתמשים באפשרויות בתפריט אפשרויות נוספות.

כדי להציג, לערוך או להריץ שאילתה שמורה, בוחרים בכרטיסייה Saved בדף Observability Analytics ומחפשים את השאילתה:

• כדי להריץ את השאילתה, לוחצים על Run.
• כדי לערוך, לראות או למחוק את השאילתה, משתמשים באפשרויות בתפריט אפשרויות נוספות.

המאמרים הבאים

• יצירת תרשים של תוצאות שאילתת SQL
• שאילתות SQL לדוגמה