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

טיפוסים בני מנייה (enums)
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

מזהי התוויות הוסרו מההודעה.