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

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

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

مراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بواجهة برمجة تطبيقات Gmail. مثل جميع الخدمات المتقدّمة في 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}`);
  }
}