قراءة جهات الاتصال وإدارتها

بعد إكمال الخطوات الواردة في قسم الاستعداد لاستخدام واجهة برمجة تطبيقات الأشخاص، تصبح جاهزًا للاطّلاع على جهات الاتصال وإدارتها.

توضح نماذج التعليمات البرمجية التالية كيفية إرسال بعض الطلبات البسيطة. للحصول على قائمة كاملة بالطُرق، راجِع المستندات المرجعية.

إدراج جهات اتصال المستخدم

للحصول على قائمة بالأشخاص في جهات اتصال المستخدم، استخدِم الرمز التالي:

البروتوكول

GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

ListConnectionsResponse response = peopleService.people().connections().list("people/me")
    .setPersonFields("names,emailAddresses")
    .execute();
List<Person> people = response.getConnections();

Python

people = people_service.people().connections()
    .list('people/me', personFields='names,emailAddresses')

PHP

$people = $people_service->people_connections->listPeopleConnections(
    'people/me', array('personFields' => 'names,emailAddresses'));

NET.

PeopleResource.ConnectionsResource.ListRequest peopleRequest =
    peopleService.People.Connections.List("people/me");
peopleRequest.PersonFields = "names,emailAddresses";
ListConnectionsResponse response = peopleRequest.Execute();
IList<Person> people = response.Connections;

إدراج جهات اتصال المستخدم التي تم تغييرها

Java

// Initial request
ListConnectionsResponse fullSyncResponse = peopleService.people().connections().list("people/me")
    .setPersonFields("metadata,names,emailAddresses")
    .setRequestSyncToken(true)
    .execute();
// Fetch all the pages
while (fullSyncResponse.getNextPageToken() != null) {
  fullSyncResponse = peopleService.people().connections().list("people/me")
      .setPersonFields("metadata,names,emailAddresses")
      .setRequestSyncToken(true)
      .setPageToken(fullSyncResponse.getNextPageToken())
      .execute();
}

// Some time passes

// Fetch incremental changes using the sync token returned in the last fullSyncResponse.
try {
  ListConnectionsResponse incrementalSyncResponse = peopleService.people().connections().list("people/me")
      .setPersonFields("metadata,names,emailAddresses")
      .setSyncToken(fullSyncResponse.getNextSyncToken())
      .execute();
  for (Person person : incrementalSyncResponse.getConnections()) {
    handlePerson(person);
  }

  // Fetch all the pages
  while (incrementalSyncResponse.getNextPageToken() != null) {
    incrementalSyncResponse = peopleService.people().connections().list("people/me")
        .setPersonFields("metadata,names,emailAddresses")
        .setSyncToken(fullSyncResponse.getNextSyncToken())
        .setPageToken(incrementalSyncResponse.getNextPageToken())
        .execute();
    for (Person person : incrementalSyncResponse.getConnections()) {
      handlePerson(person);
    }
  }
} catch (GoogleJsonResponseException e) {
  if (e.getStatusCode() == 410) {
    // Sync token expired. Make full sync request.
  }
}

void handlePerson(Person person) {
  if (person.getMetadata().getDeleted()) {
    // Handle deleted person
  } else {
    // Handle changed person
  }
}

مزيد من التفاصيل حول سلوك المزامنة على ListConnections.

البحث في جهات اتصال المستخدم

للبحث في كل جهات اتصال المستخدم، استخدِم الرمز التالي:

البروتوكول

// Warmup cache
GET /v1/people:searchContacts?query=&readMask=names,emailAddresses HTTP/1.1
Host: people.googleapis.com



// Send search request after several seconds
GET /v1/people:searchContacts?query=query&readMask=names,emailAddresses HTTP/1.1
Host: people.googleapis.com

Java

// Warmup cache
SearchResponse response = peopleService.people().searchContacts()
    .setQuery("")
    .setReadMask("names,emailAddresses")
    .execute();



// Wait a few seconds
Thread.sleep(5);



// Send search request
SearchResponse response = peopleService.people().searchContacts()
    .setQuery("query")
    .setReadMask("names,emailAddresses")
    .execute();

إنشاء جهة اتصال جديدة

من أجل إنشاء جهة اتصال جديدة، استخدم الرمز التالي:

البروتوكول

POST /v1/people:createContact HTTP/1.1
Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] }
Host: people.googleapis.com

Java

Person contactToCreate = new Person();
List<Name> names = new ArrayList<>();
names.add(new Name().setGivenName("John").setFamilyName("Doe"));
contactToCreate.setNames(names);

Person createdContact = peopleService.people().createContact(contactToCreate).execute();

استخدام الحصة لكل طلب

  • طلب قراءة مهم واحد (عمليات قراءة جهات الاتصال والملف الشخصي)
  • 1 طلب كتابة مهم (عمليات إنشاء جهات الاتصال والتحديثات)
  • رسالة واحدة للتواصل يوميًا (الإجمالي)

تعديل جهة اتصال حالية

لتعديل جهة اتصال حالية، عليك تضمين الحقل person.metadata.sources.etag في الشخص لكي يتم تعديل جهة الاتصال للتأكّد من عدم تغيير جهة الاتصال منذ آخر قراءتك لها. استخدِم الرمز التالي:

البروتوكول

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1
Body: {
    "resourceName": "resource_name",
    "etag": "etag",
    "emailAddresses": [{ "value": "john.doe@gmail.com" }],
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

List<EmailAddress> emailAddresses = new ArrayList<>();
emailAddresses.add(new EmailAddress().setValue("john.doe@gmail.com"));
contactToUpdate.setEmailAddresses(emailAddresses);

Person updatedContact = peopleService.people()
    .updateContact(contactToUpdate.getResourceName(), contactToUpdate)
    .setUpdatePersonFields("emailAddresses")
    .execute();

استخدام الحصة لكل طلب

  • طلب قراءة مهم واحد (عمليات قراءة جهات الاتصال والملف الشخصي)
  • 1 طلب كتابة مهم (عمليات إنشاء جهات الاتصال والتحديثات)
  • رسالة واحدة للتواصل يوميًا (الإجمالي)

حذف جهة اتصال حالية

لحذف جهة اتصال حالية، استخدم الرمز التالي:

البروتوكول

DELETE /v1/resource_name:deleteContact HTTP/1.1
Host: people.googleapis.com

Java

peopleService.people().deleteContact("resource_name").execute();

استخدام الحصة لكل طلب

  • 1 طلبات الكتابة (عمليات حذف جهات الاتصال وعمليات كتابة مجموعة جهات الاتصال)

إنشاء جهات اتصال جديدة بشكل مجمّع

من أجل إنشاء جهات اتصال جديدة بشكل مجمّع، استخدم الرمز التالي:

البروتوكول

POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1
Body: {
  "contacts": [
    {
      "contactPerson": {
        "names": [
          {
            "givenName": "John",
            "familyName": "Doe"
          }
        ]
      }
    }
  ]
}
Host: people.googleapis.com

Java

Person person1 = new Person();
person1.setNames(ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));
ContactToCreate contactToCreate1 = new ContactToCreate();
contactToCreate1.setContactPerson(person1);

Person person2 = new Person();
person2.setNames(ImmutableList.of(new Name().setGivenName("Bob").setFamilyName("Dylan")));
ContactToCreate contactToCreate2 = new ContactToCreate();
contactToCreate2.setContactPerson(person2);

BatchCreateContactsRequest request = new BatchCreateContactsRequest();
request.setContacts(ImmutableList.of(contactToCreate1, contactToCreate2)).setReadMask("names");

BatchCreateContactsResponse response =
    peopleService.people().batchCreateContacts(request).execute();

استخدام الحصة لكل طلب

  • 6 طلبات مهمة للقراءة (عمليات قراءة جهات الاتصال والملف الشخصي)
  • 6 طلبات كتابة مهمة (عمليات إنشاء جهات الاتصال والتحديثات)
  • 200 رسالة اتصال يومية (الإجمالي)

تعديل مجمَّع لجهات الاتصال الحالية

لتعديل جهة اتصال حالية، يجب تضمين الحقل person.metadata.sources.etag في كل شخص حتى يتم تعديل جهة الاتصال للتأكّد من عدم تغيير جهة الاتصال منذ آخر مرة قرأتها. استخدِم الرمز التالي:

البروتوكول

POST /v1/people:batchUpdateContacts?updateMask=names&readMask=names,emailAddresses HTTP/1.1
Body: {
  "contacts": {
    "resource_name": {
      "emailAddresses": [
        {
          "value": "john.doe@gmail.com"
        }
      ]
      "etag": "etag"
    }
  }
}
Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people().get("resource_name").execute();

contactToUpdate.setNames(
    ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));

BatchUpdateContactsRequest request = new BatchUpdateContactsRequest();
ImmutableMap<String, Person> map =
    ImmutableMap.of(contactToUpdate.getResourceName(), contactToUpdate);
request.setContacts(map).setUpdateMask("names").setReadMask("names,emailAddresses");

BatchUpdateContactsResponse response =
    peopleService.people().batchUpdateContacts(request).execute();

استخدام الحصة لكل طلب

  • 6 طلبات مهمة للقراءة (عمليات قراءة جهات الاتصال والملف الشخصي)
  • 6 طلبات كتابة مهمة (عمليات إنشاء جهات الاتصال والتحديثات)
  • 200 رسالة اتصال يومية (الإجمالي)

حذف جهات الاتصال الحالية بشكل مجمّع

من أجل حذف جهات الاتصال الحالية بشكل مجمّع، استخدِم الرمز التالي:

البروتوكول

POST /v1/people:batchDeleteContacts HTTP/1.1
Body: {"resource_names": ["resource_name"]}
Host: people.googleapis.com

Java

BatchDeleteContactsRequest request = new BatchDeleteContactsRequest();

request.setResourceNames(ImmutableList.of(resource_name));

peopleService.people().batchDeleteContacts(request).execute();

استخدام الحصة لكل طلب

  • 10 طلبات كتابة (عمليات حذف جهات الاتصال وكتابة مجموعة جهات الاتصال)