Method: people.connections.list

提供已驗證使用者的聯絡人清單。

同步權杖的有效期限為完整同步後的 7 天。同步權杖過期的要求會收到 google.rpc.ErrorInfo，原因為「EXPIRED_SYNC_TOKEN」。如果發生這類錯誤，用戶端不應在沒有 syncToken 的情況下提出完整的同步要求。

完整同步處理要求的第一頁有額外的配額。如果超出配額，系統會傳回 429 錯誤。這項配額已修正，無法增加。

指定 syncToken 後，系統會將自上次同步後刪除的資源，以 PersonMetadata.deleted 設為 true 的人物形式傳回。

指定 pageToken 或 syncToken 時，所有其他要求參數都必須與第一次呼叫相符。

寫入作業的同步處理要求可能會延遲幾分鐘才傳送。增量同步功能不適用於寫入後讀取的用途。

如需使用範例，請參閱「列出使用者已變更的聯絡人」一文。

HTTP 要求

GET https://people.googleapis.com/v1/{resourceName=people/*}/connections

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
resourceName
(deprecated)

string

必要欄位。要傳回連線的資源名稱。只有 people/me 有效。

查詢參數

參數
pageToken

string

選用設定。屬於接收自前一個回應 nextPageToken 的網頁權杖。提供此項目即可擷取後續網頁。

進行分頁時，提供至 people.connections.list 的所有其他參數須與提供網頁權杖的第一個呼叫相符。
pageSize

integer

選用設定。要在回應中加入的連線數量。有效值介於 1 到 1000 (含首尾) 之間。如果未設定或已設定為 0，預設值為 100。
sortOrder

enum (SortOrder)

選用設定。連線的排序順序。預設值為 LAST_MODIFIED_ASCENDING。
requestSyncToken

boolean

選用設定。回應是否應在結果的最後一頁中傳回 nextSyncToken。此函式可在要求 syncToken 上設定，以取得自上次要求以來的漸進式變更。

如要進一步瞭解同步行為，請參閱 people.connections.list。
syncToken

string

選用設定。從先前回應收到的同步作業權杖 nextSyncToken 提供這項資訊，即可只擷取自上次要求以來變更的資源。

同步處理時，提供給 people.connections.list 的所有其他參數都必須與提供同步權杖的第一個呼叫相符。

如要進一步瞭解同步處理行為，請前往 people.connections.list。
requestMask
(deprecated)

object (RequestMask)

選用設定。已淘汰 (請改用 personFields)

這項遮罩可將結果限制為部分人物欄位。
personFields

string (FieldMask format)

必要欄位。欄位遮罩可限制系統傳回每個人的哪些欄位。如要指定多個欄位，請以半形逗號分隔。有效值如下：

  • addresses
  • ageRanges
  • 傳記
  • 生日
  • calendarUrls
  • clientData
  • coverPhotos
  • emailAddresses
  • 活動
  • externalIds
  • 性別
  • imClients
  • 興趣
  • locales
  • 位置
  • 會籍
  • 中繼資料
  • miscKeywords
  • 名稱
  • 暱稱
  • 職業
  • 機構組織
  • phoneNumbers
  • 相片
  • 關係
  • sipAddresses
  • skills
  • 網址
  • userDefined
sources[]

enum (ReadSourceType)

選用設定。指定要傳回哪些來源類型的遮罩。如果未設定，預設為 READ_SOURCE_TYPE_CONTACT 和 READ_SOURCE_TYPE_PROFILE。

要求主體

要求主體必須為空白。

回應主體

對已驗證使用者連線要求的回應。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "connections": [
    {
      object (Person)
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "totalPeople": integer,
  "totalItems": integer
}
欄位
connections[]

object (Person)

要求者連結的使用者清單。
nextPageToken

string

可做為 pageToken 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。
nextSyncToken

string

可做為 syncToken 傳送的權杖，用來擷取自上次要求以來的變更。要求必須設定 requestSyncToken，才能傳回同步處理權杖。回應分頁後，只有最後一個頁面會含有 nextSyncToken。
totalPeople
(deprecated)

integer

已淘汰 (請使用 totalItems) 名單中不含分頁的使用者總數。
totalItems

integer

清單中的項目總數 (不含分頁)。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/contacts
  • https://www.googleapis.com/auth/contacts.readonly

詳情請參閱授權指南。

SortOrder

連線清單的排序順序。只有在未要求同步處理時才使用。

列舉
LAST_MODIFIED_ASCENDING 依變更時間排序使用者；較舊存在
LAST_MODIFIED_DESCENDING 依變更時間排序使用者；上傳較新的資料
FIRST_NAME_ASCENDING 依姓氏排序。
LAST_NAME_ASCENDING 依姓氏排序使用者。