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 之间（含 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
  • 地理位置
  • memberships
  • 元数据
  • 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 按姓氏对人物进行排序。