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

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

مراجع

للحصول على معلومات تفصيلية حول هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بواجهة برمجة التطبيقات Gmail API. مثل جميع الخدمات المتقدّمة في "برمجة التطبيقات"، تستخدم خدمة 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) {
        threadList.threads.forEach(function (thread) {
          console.log('Snippet: %s', 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) {
        history.forEach(function (record) {
          record.messages.forEach(function (message) {
            if (changed.indexOf(message.id) === -1) {
              changed.push(message.id);
            }
          });
        });
      }
      pageToken = recordList.nextPageToken;
    } while (pageToken);

    changed.forEach(function (id) {
      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}`);
  }
}