عرض قائمة برسائل Gmail

توضّح هذه الصفحة كيفية استدعاء طريقة users.messages.list في Gmail API.

تعرض الطريقة مصفوفة من موارد Message في Gmail تحتوي على الرسالة id وthreadId. لاسترداد تفاصيل الرسالة الكاملة، استخدِم طريقة users.messages.get.

المتطلبات الأساسية

Python

مشروع على Google Cloud تم تفعيل واجهة برمجة التطبيقات Gmail API فيه للاطّلاع على الخطوات، أكمل دليل البدء السريع حول Gmail API Python.

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

تتيح طريقة users.messages.list استخدام عدة مَعلمات طلب بحث لفلترة الرسائل:

  • ‫maxResults: الحد الأقصى لعدد الرسائل التي سيتم عرضها (القيمة التلقائية هي 100، والحد الأقصى هو 500).
  • pageToken: رمز مميّز لاسترداد صفحة معيّنة من النتائج.
  • ‫q: سلسلة طلب البحث لفلترة الرسائل، مثل from:someuser@example.com is:unread".
  • labelIds: لعرض الرسائل التي تتضمّن تصنيفات تطابق جميع معرّفات التصنيفات المحدّدة فقط.
  • includeSpamTrash: تضمين الرسائل من SPAM وTRASH في النتائج

عيّنة تعليمات برمجية

Python

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

gmail/snippet/list_messages.py
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]


def main():
    """Shows basic usage of the Gmail API.
    Lists the user's Gmail messages.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        # Call the Gmail API
        service = build("gmail", "v1", credentials=creds)
        results = (
            service.users().messages().list(userId="me", labelIds=["INBOX"]).execute()
        )
        messages = results.get("messages", [])

        if not messages:
            print("No messages found.")
            return

        print("Messages:")
        for message in messages:
            print(f'Message ID: {message["id"]}')
            msg = (
                service.users().messages().get(userId="me", id=message["id"]).execute()
            )
            print(f'  Subject: {msg["snippet"]}')

    except HttpError as error:
        # TODO(developer) - Handle errors from gmail API.
        print(f"An error occurred: {error}")


if __name__ == "__main__":
    main()

تعرض الطريقة users.messages.list نص استجابة يتضمّن ما يلي:

  • messages[]: صفيف من مراجع Message.
  • nextPageToken: للطلبات التي تتضمّن صفحات متعددة من النتائج، هذا الحقل يمثّل رمزًا مميّزًا يمكن استخدامه مع طلبات لاحقة لعرض المزيد من الرسائل.
  • ‫resultSizeEstimate: إجمالي عدد النتائج المقدَّر

لاسترداد محتوى الرسالة الكامل والبيانات الوصفية، استخدِم الحقل message.id لاستدعاء الطريقة users.messages.get.