Method: users.history.list

تعرض هذه السمة سجلّ جميع التغييرات التي تم إجراؤها على صندوق البريد المحدّد. يتم عرض نتائج السجلّ بترتيب زمني (زيادة historyId). لمزيد من المعلومات، يُرجى الاطّلاع على مزامنة البرامج مع Gmail.

طلب HTTP

GET https://gmail.googleapis.com/gmail/v1/users/{userId}/history

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المَعلمات
userId

string

عنوان البريد الإلكتروني للمستخدِم يمكن استخدام القيمة الخاصة me للإشارة إلى المستخدم الذي تمّت مصادقته.

مَعلمات طلب البحث

المَعلمات
maxResults

integer (uint32 format)

الحدّ الأقصى لعدد سجلّات السجلّ المطلوب عرضها. القيمة التلقائية لهذا الحقل هي 100. الحد الأقصى المسموح به لهذه القيمة هو 500.
pageToken

string

رمز مميّز للصفحة لاسترداد صفحة معيّنة من النتائج في القائمة.
startHistoryId

string

الحقل مطلوب. تعرض هذه السمة سجلّات المحفوظات بعد startHistoryId المحدّد. يجب الحصول على startHistoryId المقدَّم من historyId رسالة أو سلسلة محادثات أو ردّ list سابق. تزداد أرقام التعريف السابقة ترتيبًا زمنيًا، ولكنّها ليست متجاورة، إذ تتخلّلها فجوات عشوائية بين أرقام التعريف الصالحة. يؤدي تقديم startHistoryId غير صالح أو منتهي الصلاحية عادةً إلى عرض رمز الخطأ HTTP 404. يكون historyId صالحًا عادةً لمدة أسبوع على الأقل، ولكن في بعض الحالات النادرة، قد يكون صالحًا لبضع ساعات فقط. إذا تلقّيت استجابة HTTP 404 خطأ، يجب أن ينفّذ تطبيقك عملية مزامنة كاملة. إذا لم تتلقَّ أي nextPageToken في الردّ، يعني ذلك أنّه لا تتوفّر أي تحديثات لاستردادها ويمكنك تخزين historyId الذي تم إرجاعه لطلبه في المستقبل.
labelId

string

عرض الرسائل التي تحمل تصنيفًا مطابقًا لرقم التعريف فقط
historyTypes[]

enum (HistoryType)

أنواع السجلّ المطلوب أن تعرضه الدالة

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "history": [
    {
      object (History)
    }
  ],
  "nextPageToken": string,
  "historyId": string
}
الحقول
history[]

object (History)

قائمة بسجلات السجلّ أي messages مضمّن في الردّ سيحتوي عادةً على الحقلين id وthreadId فقط.
nextPageToken

string

الرمز المميّز للصفحة المطلوب استرداد الصفحة التالية من النتائج في القائمة.
historyId

string

معرّف سجلّ السجلّ الحالي لعلبة البريد

نطاقات الأذونات

يجب توفير أحد نطاقات OAuth التالية:

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.metadata

لمزيد من المعلومات، يمكنك الاطّلاع على دليل التفويض.

HistoryType

عمليات التعداد
messageAdded
messageDeleted
labelAdded
labelRemoved

السجلّ

سجلّ بالتغييرات التي تم إجراؤها على صندوق بريد المستخدم قد يؤثّر كل تغيير في السجلّ في عدّة رسائل بطرق متعدّدة.

تمثيل JSON 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ],
  "messagesAdded": [
    {
      object (MessageAdded)
    }
  ],
  "messagesDeleted": [
    {
      object (MessageDeleted)
    }
  ],
  "labelsAdded": [
    {
      object (LabelAdded)
    }
  ],
  "labelsRemoved": [
    {
      object (LabelRemoved)
    }
  ]
}
الحقول
id

string

معرّف تسلسل صندوق البريد
messages[]

object (Message)

قائمة الرسائل التي تم تغييرها في سجلّ المحفوظات هذا قد تكرّر الحقول الخاصة بأنواع التغييرات المحدّدة، مثل messagesAdded، الرسائل في هذا الحقل. ننصحك باستخدام حقول نوع التغيير المحدّدة بدلاً من ذلك.
messagesAdded[]

object (MessageAdded)

الرسائل المُضافة إلى صندوق البريد في سجلّ المحفوظات هذا
messagesDeleted[]

object (MessageDeleted)

الرسائل المحذوفة (غير الموضوعة في المهملات) من صندوق البريد في سجلّ هذا التاريخ
labelsAdded[]

object (LabelAdded)

التصنيفات التي تمت إضافتها إلى الرسائل في سجلّ المحادثات هذا
labelsRemoved[]

object (LabelRemoved)

التصنيفات التي تمت إزالتها من الرسائل في سجلّ المحادثات هذا

MessageAdded

تمثيل JSON 
{
  "message": {
    object (Message)
  }
}
الحقول
message

object (Message)

MessageDeleted

تمثيل JSON 
{
  "message": {
    object (Message)
  }
}
الحقول
message

object (Message)

LabelAdded

تمثيل JSON 
{
  "message": {
    object (Message)
  },
  "labelIds": [
    string
  ]
}
الحقول
message

object (Message)
labelIds[]

string

معرّفات التصنيفات التي تمت إضافتها إلى الرسالة

LabelRemoved

تمثيل JSON 
{
  "message": {
    object (Message)
  },
  "labelIds": [
    string
  ]
}
الحقول
message

object (Message)
labelIds[]

string

معرّفات التصنيفات التي تمت إزالتها من الرسالة