خدمة Gmail المتقدِّمة

للوصول إلى ميزات إضافية ومعلومات تفصيلية من Gmail API

تتيح لك خدمة Gmail المتقدّمة استخدام Gmail API في Google Apps Script. وكما هو الحال مع خدمة Gmail المضمّنة في Apps Script، تتيح واجهة برمجة التطبيقات هذه للبرامج النصية العثور على سلاسل المحادثات والرسائل والتصنيفات وتعديلها في صندوق بريد Gmail. في معظم الحالات، تكون الخدمة المضمّنة أسهل في الاستخدام، ولكن هذه الخدمة المتقدّمة توفّر بعض الميزات الإضافية وإمكانية الوصول إلى معلومات أكثر تفصيلاً حول محتوى Gmail.

هذه خدمة متقدّمة يجب تفعيلها قبل الاستخدام.

مراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بـ Gmail API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة Gmail المتقدّمة العناصر والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، اطّلِع على كيفية تحديد التواقيع.

للإبلاغ عن المشاكل والعثور على دعم آخر، يُرجى الاطّلاع على دليل دعم Gmail.

نموذج التعليمات البرمجية

يستخدم نموذج الرمز البرمجي التالي الإصدار 1 من واجهة برمجة التطبيقات.

عرض معلومات التصنيف

يوضّح المثال التالي كيفية إدراج جميع معلومات التصنيف الخاصة بالمستخدم. ويشمل ذلك اسم التصنيف ونوعه ومعرّفه وإعدادات مستوى العرض.

advanced/gmail.gs
/**
 * Lists the user's labels, including name, type,
 * ID and visibility information.
 */
function listLabelInfo() {
  try {
    const response = Gmail.Users.Labels.list("me");
    for (let i = 0; i < response.labels.length; i++) {
      const label = response.labels[i];
      console.log(JSON.stringify(label));
    }
  } catch (err) {
    console.log(err);
  }
}

مقتطفات البريد الوارد الخاصة بالقوائم

يوضّح المثال التالي كيفية إدراج مقتطفات نصية مرتبطة بكل سلسلة محادثات في البريد الوارد للمستخدم. لاحظ استخدام رموز الصفحات للوصول إلى القائمة الكاملة للنتائج.

advanced/gmail.gs
/**
 * Lists, for each thread in the user's Inbox, a
 * snippet associated with that thread.
 */
function listInboxSnippets() {
  try {
    let pageToken;
    do {
      const threadList = Gmail.Users.Threads.list("me", {
        q: "label:inbox",
        pageToken: pageToken,
      });
      if (threadList.threads && threadList.threads.length > 0) {
        for (const thread of threadList.threads) {
          console.log(`Snippet: ${thread.snippet}`);
        }
      }
      pageToken = threadList.nextPageToken;
    } while (pageToken);
  } catch (err) {
    console.log(err);
  }
}

عرض السجلّ الحديث

يوضّح المثال التالي كيفية تسجيل سجلّ الأنشطة الحديثة. على وجه التحديد، يستردّ هذا المثال رقم تعريف سجلّ المحفوظات المرتبط بأحدث رسالة أرسلها المستخدم، ثم يسجّل أرقام تعريف الرسائل التي تم تغييرها منذ ذلك الوقت. يتم تسجيل كل رسالة تم تغييرها مرة واحدة فقط، بغض النظر عن عدد أحداث التغيير في سجلّات السجلّ. لاحظ استخدام رموز الصفحات للوصول إلى القائمة الكاملة بالنتائج.

advanced/gmail.gs
/**
 * Gets a history record ID associated with the most
 * recently sent message, then logs all the message IDs
 * that have changed since that message was sent.
 */
function logRecentHistory() {
  try {
    // Get the history ID associated with the most recent
    // sent message.
    const sent = Gmail.Users.Threads.list("me", {
      q: "label:sent",
      maxResults: 1,
    });
    if (!sent.threads || !sent.threads[0]) {
      console.log("No sent threads found.");
      return;
    }
    const historyId = sent.threads[0].historyId;

    // Log the ID of each message changed since the most
    // recent message was sent.
    let pageToken;
    const changed = [];
    do {
      const recordList = Gmail.Users.History.list("me", {
        startHistoryId: historyId,
        pageToken: pageToken,
      });
      const history = recordList.history;
      if (history && history.length > 0) {
        for (const record of history) {
          for (const message of record.messages) {
            if (changed.indexOf(message.id) === -1) {
              changed.push(message.id);
            }
          }
        }
      }
      pageToken = recordList.nextPageToken;
    } while (pageToken);

    for (const id of changed) {
      console.log("Message Changed: %s", id);
    }
  } catch (err) {
    console.log(err);
  }
}

عرض الرسائل في قائمة

يوضّح المثال التالي كيفية عرض الرسائل غير المقروءة لمستخدم Gmail.

advanced/gmail.gs
/**
 * Lists unread messages in the user's inbox using the advanced Gmail service.
 */
function listMessages() {
  // The special value 'me' indicates the authenticated user.
  const userId = "me";

  // Define optional parameters for the request.
  const options = {
    maxResults: 10, // Limit the number of messages returned.
    q: "is:unread", // Search for unread messages.
  };

  try {
    // Call the Gmail.Users.Messages.list method.
    const response = Gmail.Users.Messages.list(userId, options);
    const messages = response.messages;
    console.log("Unread Messages:");

    for (const message of messages) {
      console.log(`- Message ID: ${message.id}`);
    }
  } catch (err) {
    // Log any errors to the Apps Script execution log.
    console.log(`Failed with error: ${err.message}`);
  }
}