Method: people.connections.list

Cung cấp danh sách người liên hệ của người dùng đã xác thực.

Mã thông báo đồng bộ hoá sẽ hết hạn sau 7 ngày kể từ khi đồng bộ hoá toàn bộ. Yêu cầu có mã thông báo đồng bộ hoá đã hết hạn sẽ gặp lỗi google.rpc.ErrorInfo kèm theo lý do "EXPIRED_SYNC_TOKEN". Trong trường hợp xảy ra lỗi này, các ứng dụng nên thực hiện yêu cầu đồng bộ hoá đầy đủ mà không cần có syncToken.

Trang đầu tiên của yêu cầu đồng bộ hoá đầy đủ sẽ có hạn mức bổ sung. Nếu vượt quá hạn mức, hàm sẽ trả về lỗi 429. Hạn mức này là cố định và không thể tăng.

Khi syncToken được chỉ định, các tài nguyên đã xoá kể từ lần đồng bộ hoá gần nhất sẽ được trả về dưới dạng một người với PersonMetadata.deleted được đặt thành true.

Khi bạn chỉ định pageToken hoặc syncToken, tất cả các tham số yêu cầu khác phải khớp với lệnh gọi đầu tiên.

Đối với các yêu cầu đồng bộ hoá, hoạt động ghi có thể bị trễ vài phút khi truyền tải. Tính năng đồng bộ hoá gia tăng không dành cho các trường hợp sử dụng đọc sau khi ghi.

Xem ví dụ về cách sử dụng tại phần Liệt kê những người liên hệ đã thay đổi của người dùng.

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Thông số
resourceName
(deprecated)

string

Bắt buộc. Tên tài nguyên để trả về các kết nối. Chỉ people/me là hợp lệ.

Tham số truy vấn

Thông số
pageToken

string

Không bắt buộc. Mã thông báo trang, đã nhận được từ phản hồi trước đó nextPageToken. Cung cấp giá trị này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác được cung cấp cho people.connections.list phải khớp với lệnh gọi đầu tiên đã cung cấp mã thông báo trang.
pageSize

integer

Không bắt buộc. Số lượng kết nối cần đưa vào phản hồi. Giá trị hợp lệ nằm trong khoảng từ 1 đến 1000. Giá trị mặc định là 100 nếu không được đặt hoặc được đặt thành 0.
sortOrder

enum (SortOrder)

Không bắt buộc. Thứ tự sắp xếp các kết nối. Giá trị mặc định là LAST_MODIFIED_ASCENDING.
requestSyncToken

boolean

Không bắt buộc. Liệu phản hồi có trả về nextSyncToken trên trang kết quả cuối cùng hay không. Bạn có thể dùng đối tượng này để nhận các thay đổi gia tăng kể từ yêu cầu gần đây nhất bằng cách đặt đối tượng này trong yêu cầu syncToken.

Thông tin chi tiết khác về hành vi đồng bộ hoá tại people.connections.list.
syncToken

string

Không bắt buộc. Mã thông báo đồng bộ hoá, nhận được từ một phản hồi trước đó nextSyncToken Cung cấp mã này để chỉ truy xuất các tài nguyên đã thay đổi kể từ yêu cầu gần đây nhất.

Khi đồng bộ hoá, tất cả các tham số khác được cung cấp cho people.connections.list phải khớp với lệnh gọi đầu tiên đã cung cấp mã thông báo đồng bộ hoá.

Bạn có thể xem thêm thông tin chi tiết về hoạt động đồng bộ hoá tại people.connections.list.
requestMask
(deprecated)

object (RequestMask)

Không bắt buộc. KHÔNG DÙNG NỮA (Vui lòng sử dụng personFields)

Mặt nạ để hạn chế kết quả cho một nhóm nhỏ các trường về người dùng.
personFields

string (FieldMask format)

Bắt buộc. Mặt nạ trường để hạn chế các trường mà mỗi người dùng được trả về. Bạn có thể chỉ định nhiều trường bằng cách dùng dấu phẩy để phân tách các trường. Các giá trị hợp lệ là:

  • địa chỉ
  • ageRanges
  • tiểu sử
  • ngày sinh
  • calendarUrls
  • clientData
  • coverPhotos
  • emailAddresses
  • sự kiện
  • externalIds
  • giới tính
  • imClients
  • sở thích
  • ngôn ngữ
  • vị trí
  • của kênh
  • siêu dữ liệu
  • miscKeywords
  • tên
  • biệt hiệu
  • nghề nghiệp
  • tổ chức
  • phoneNumbers
  • ảnh
  • quan hệ
  • sipAddresses
  • kỹ năng
  • url
  • userDefined
sources[]

enum (ReadSourceType)

Không bắt buộc. Mặt nạ cho biết các loại nguồn cần trả về. Giá trị mặc định là READ_SOURCE_TYPE_CONTACT và READ_SOURCE_TYPE_PROFILE nếu không được đặt.

Nội dung yêu cầu

Nội dung yêu cầu phải trống.

Nội dung phản hồi

Phản hồi cho yêu cầu kết nối của người dùng đã được xác thực.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "connections": [
    {
      object (Person)
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "totalPeople": integer,
  "totalItems": integer
}
Trường
connections[]

object (Person)

Danh sách những người mà người yêu cầu đã kết nối.
nextPageToken

string

Mã thông báo có thể được gửi dưới dạng pageToken để truy xuất trang tiếp theo. Nếu trường này bị bỏ qua thì sẽ không có trang tiếp theo.
nextSyncToken

string

Mã thông báo có thể được gửi dưới dạng syncToken để truy xuất các thay đổi kể từ yêu cầu gần đây nhất. Yêu cầu phải đặt requestSyncToken để trả về mã thông báo đồng bộ hoá. Khi phản hồi được phân trang, chỉ trang cuối cùng mới chứa nextSyncToken.
totalPeople
(deprecated)

integer

KHÔNG DÙNG NỮA (Vui lòng sử dụng totalItems) Tổng số người trong danh sách không có tính năng phân trang.
totalItems

integer

Tổng số mục trong danh sách không phân trang.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem Hướng dẫn uỷ quyền.

SortOrder

Thứ tự sắp xếp danh sách các kết nối. Tính năng này chỉ được sử dụng nếu không có yêu cầu đồng bộ hoá.

Enum
LAST_MODIFIED_ASCENDING Sắp xếp người dùng theo thời điểm thay đổi; các mục cũ hơn trước.
LAST_MODIFIED_DESCENDING Sắp xếp người dùng theo thời điểm thay đổi; các mục mới hơn sẽ xuất hiện trước.
FIRST_NAME_ASCENDING Sắp xếp mọi người theo tên.
LAST_NAME_ASCENDING Sắp xếp người dùng theo họ.