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 收到的頁面憑證。請提供這個 ID 以擷取後續網頁。

進行分頁時，提供給 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
  • 年齡層
  • 傳記
  • 生日
  • calendarurl
  • 用戶端資料
  • 封面相片
  • emailAddresses
  • 活動
  • 外部 ID
  • 性別
  • imClient
  • 興趣
  • locales
  • 地點
  • 會籍
  • 中繼資料
  • 錯誤關鍵字
  • names
  • 暱稱
  • 職業
  • 機構
  • phoneNumbers
  • 相片
  • 關係
  • SIP 位址
  • skills
  • 網址
  • 使用者定義
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 依姓氏排序使用者。