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

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

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