Method: users.history.list

يسرد سجل جميع التغييرات التي طرأت على صندوق البريد المحدد. يتم عرض نتائج السجلّ بترتيب زمني (زيادة بنسبة historyId).

طلب 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

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