יצירה וניהול של ערוצי התראות באמצעות API

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

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

מידע על ה-API

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

  • שליחת קוד אימות
  • יצירת קוד להעתקת סטטוס האימות של ערוץ מאומת לערוצים זהים אחרים באותו פרויקט או בפרויקט חדש
  • אימות הערוץ באמצעות הקוד שנוצר בשתי הפעולות הקודמות

מידע נוסף זמין במסמכי העיון בנושא notificationChannels.

מגבלות

  • סוגי ערוצים שהוצאו משימוש: סוגי הערוצים campfire ו-hipchat הוצאו משימוש. אל תיצרו ערוצים חדשים מהסוגים האלה.
  • מדיניות אחסון הודעות ב-Pub/Sub: אם מגדירים מדיניות אחסון הודעות או הגבלות על מיקום אחסון הנתונים בנושא ב-Pub/Sub, יכול להיות שלא תהיה ל-Monitoring אפשרות לפרסם בנושא. מידע נוסף זמין במאמר בנושא שגיאה FAILED_PRECONDITION.
  • קריאות מקבילות ל-API: כשיוצרים, משנים או מוחקים ערוץ התראות בפרויקט Google Cloud , צריך לתכנן את האפליקציה כך שהיא תפעיל את Cloud Monitoring API משרשור יחיד.

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

רשימה של סוגי ערוצי התראות

ב-Monitoring יש מספר סוגים מובנים של ערוצי התראות. כל אחד מהסוגים האלה מתואר בNotificationChannelDescriptor. לכל מתאר יש שדה type שהערך שלו מזהה את סוג הערוץ כשיוצרים מופע של ערוץ. כדי לאחזר רשימה של סוגי ערוצים שאפשר ליצור באמצעות Cloud Monitoring API או Google Cloud CLI, מזינים את הפקודה הבאה:

$ gcloud beta monitoring channel-descriptors list --format='value(type)'
campfire
email
google_chat
hipchat
pagerduty
pubsub
slack
sms
webhook_basicauth
webhook_tokenauth

אם ערוץ ההתראות המועדף שלכם לא נתמך, כדאי ליצור צינור עיבוד נתונים שמסתמך על שליחת ההתראות ל-Pub/Sub. דוגמה ל-Python שמשתמשת ב-Flask זמינה במאמר יצירת התראות בהתאמה אישית באמצעות Cloud Monitoring ו-Cloud Run. דוגמאות נוספות זמינות במאגר cloud-alerting-notification-forwarding Git.

רשימה של כל סוגי הערוצים

כדי לאחזר את כל תיאורי הערוצים ב Google Cloud פרויקט, משתמשים בפקודה gcloud beta monitoring channel-descriptors list או בשיטת ה-API‏ notificationChannelDescriptors.list. המתארים שאוחזרו הם לקריאה בלבד.

gcloud beta monitoring channel-descriptors list

אם הפקודה list מופעלת בהצלחה, היא מספקת רשימה של כל תיאורי הערוצים בפרויקט שצוין. לדוגמה, תיאור הערוץ email יופיע ברשימה כך:

---
description: A channel that sends notifications via email.
displayName: Email
labels:
- description: An address to send email.
  key: email_address
name: projects/[PROJECT_ID]/notificationChannelDescriptors/email
type: email
---

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

  • ‫name: שם המשאב המלא של מתאר הערוץ.
  • ‫type: החלק בשם שמציין את סוג הערוץ.
  • ‫displayName: תיאור של השדה type, למטרות תצוגה.
  • ‫description: תיאור קצר של הערוץ.
  • ‫labels: קבוצה של שדות שספציפיים לסוג הערוץ. לכל סוג ערוץ יש קבוצה משלו של תוויות.

כשיוצרים ערוץ, נוצר גם שדה enabled עם הערך true כברירת מחדל.

הצגת רשימה של סוג ערוץ ספציפי

אם אתם מחפשים תיאור ספציפי ואתם יודעים את השם שלו, אתם יכולים להשתמש ב-gcloud beta monitoring channel-descriptors describe או בשיטת ה-API‏ notificationChannelDescriptors.get. השם של מתאר הערוץ הוא בפורמט projects/[PROJECT_ID]/notificationChannelDescriptors/[CHANNEL_TYPE]. ‫[CHANNEL_TYPE] חייב להיות אחד מהסוגים שצוינו קודם. לדוגמה:

gcloud beta monitoring channel-descriptors describe email

gcloud beta monitoring channel-descriptors describe projects/[PROJECT_ID]/notificationChannelDescriptors/email

מידע נוסף זמין במאמרים בנושא gcloud beta monitoring channel-descriptors list וdescribe. הפקודה describe תואמת ל-method notificationChannelDescriptors.get ב-API.

יצירת ערוץ התראות

אפשר ליצור ערוצי התראות עבור פרויקטים ב- Google Cloud באמצעות קובצי JSON או YAML באמצעות Google Cloud CLI, ואפשר גם ליצור אותם באופן פרוגרמטי.

כדי ליצור ערוץ התראות, צריך לספק ערכים לשדות בתיאור שלו. רובם, כמו type, נפוצים בכל תיאורי ערוצי ההתראות. אפשר לעיין בnotificationChannelDescriptors.

לכל תיאור יש גם קבוצה של תוויות, והקבוצה הזו משתנה בין התיאורים. כדי לראות את קבוצת התוויות של מתאר מסוים, מאחזרים את המתאר באמצעות הפקודה gcloud beta monitoring channel-descriptors describe שמתוארת במאמר רשימת הסוגים של ערוצי התראות. לדוגמה, כשמאחזרים את תיאור הערוץ email מוצגת תווית אחת:

    labels:
    - description: An address to send email.
      key: email_address

תיאור הערוץ pubsub מכיל גם תווית אחת שמזהה את נושא ה-Pub/Sub. עם זאת, ערוצים יכולים להכיל כמה תוויות. לדוגמה, לתיאור הערוץ slack יש שתי תוויות:

    labels:
    - description: A permanent authentication token provided by Slack. This field is obfuscated by returning only a few characters of the key when fetched.
      key: auth_token
    - description: The Slack channel to which to post notifications.
      key: channel_name

כשמאחזרים את webhook_basicauth תיאור הערוץ מוצגות כמה תוויות:

    labels:
    - description: The password. The field is obfuscated when the channel is fetched.
      key: password
    - description: The public URL to which to publish the webhook.
      key: url
    - description: The username.
      key: username

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

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

הערוצים מופעלים כברירת מחדל. אם רוצים ליצור ערוץ לא פעיל, אפשר לכלול את השדה enabled עם הערך false.

בדוגמאות הבאות מוסבר איך ליצור ערוצי התראות.

דוגמה: יצירת ערוץ התראות Pub/Sub באמצעות ה-CLI של gcloud

כדי ליצור ערוץ התראות בפרויקט Google Cloud , משתמשים בפקודה gcloud beta monitoring channels create. כדי לטעון את הערוץ מקובץ, משתמשים בדגל --channel-content-from-file כדי לציין את הקובץ.

לדוגמה, הקטע הבא מציג את ההגדרה של ערוץ התראות חדש pubsub ב-JSON:

    {
      "type": "pubsub",
      "displayName": "Notifications",
      "description": "Pub/Sub channel for notifications",
      "labels": {
        "topic": "projects/[PROJECT_ID]/topics/notificationTopic"
      },
    }

הערך type (pubsub) ומפתח התווית היחיד (topic) תואמים לשדות type ו-labels.key בתיאור הערוץ המתאים.

בדוגמה הבאה נוצר ערוץ Pub/Sub חדש מקובץ pubsub-channel.json:

gcloud beta monitoring channels create --channel-content-from-file="pubsub-channel.json"

אם הפקודה מסתיימת ללא שגיאות, היא מחזירה את השם של הערוץ החדש. לדוגמה:

Created notification channel [projects/[PROJECT_ID]/notificationChannels/1355376463305411567].

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

דוגמה: יצירת ערוץ התראות באמצעות ספריות לקוח

בדוגמאות הבאות מוצגות דרכים ליצור ערוץ התראות באמצעות ספריית לקוח:

C#

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 

static void RestorePolicies(string projectId, string filePath)
{
    var policyClient = AlertPolicyServiceClient.Create();
    var channelClient = NotificationChannelServiceClient.Create();
    List<Exception> exceptions = new List<Exception>();
    var backup = JsonConvert.DeserializeObject<BackupRecord>(
        File.ReadAllText(filePath), new ProtoMessageConverter());
    var projectName = new ProjectName(projectId);
    bool isSameProject = projectId == backup.ProjectId;
    // When a channel is recreated, rather than updated, it will get
    // a new name.  We have to update the AlertPolicy with the new
    // name.  Track the names in this map.
    var channelNameMap = new Dictionary<string, string>();
    foreach (NotificationChannel channel in backup.Channels)
    {
        try
        {
            bool updated = false;
            Console.WriteLine("Updating channel.\n{0}",
                channel.DisplayName);
            // This field is immutable and it is illegal to specify a
            // non-default value (UNVERIFIED or VERIFIED) in the
            // Create() or Update() operations.
            channel.VerificationStatus = NotificationChannel.Types
                .VerificationStatus.Unspecified;
            if (isSameProject)
                try
                {
                    channelClient.UpdateNotificationChannel(
                        null, channel);
                    updated = true;
                }
                catch (Grpc.Core.RpcException e)
                when (e.Status.StatusCode == StatusCode.NotFound)
                { }
            if (!updated)
            {
                // The channel no longer exists.  Recreate it.
                string oldName = channel.Name;
                channel.Name = null;
                var response = channelClient.CreateNotificationChannel(
                    projectName, channel);
                channelNameMap.Add(oldName, response.Name);
            }
        }
        catch (Exception e)
        {
            // If one failed, continue trying to update the others.
            exceptions.Add(e);
        }
    }
    foreach (AlertPolicy policy in backup.Policies)
    {
    }
    if (exceptions.Count > 0)
    {
        throw new AggregateException(exceptions);
    }
}

Node.js

כדי לבצע אימות ב-Monitoring, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית. 


// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates clients
const alertClient = new monitoring.AlertPolicyServiceClient();
const notificationClient = new monitoring.NotificationChannelServiceClient();

async function replaceChannels() {
  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'YOUR_PROJECT_ID';
  // const alertPolicyId = '123456789012314';
  // const channelIds = [
  //   'channel-1',
  //   'channel-2',
  //   'channel-3',
  // ];

  const notificationChannels = channelIds.map(id =>
    notificationClient.projectNotificationChannelPath(projectId, id)
  );

  for (const channel of notificationChannels) {
    const updateChannelRequest = {
      updateMask: {
        paths: ['enabled'],
      },
      notificationChannel: {
        name: channel,
        enabled: {
          value: true,
        },
      },
    };
    try {
      await notificationClient.updateNotificationChannel(
        updateChannelRequest
      );