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
  • names
  • 暱稱
  • 職業
  • organizations
  • phoneNumbers
  • 相片
  • 關係
  • sipAddresses
  • skills
  • urls
  • 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 依姓氏排序使用者。