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

بعد إكمال الخطوات الواردة في مقالة الاستعداد لاستخدام People API، ستكون جاهزًا لقراءة جهات الاتصال وإدارتها.

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

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

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

البروتوكولJavaPythonPHPNET.
GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1
Host: people.googleapis.com
 
ListConnectionsResponse response = peopleService.people().connections().list("people/me")
    .setPersonFields("names,emailAddresses")
    .execute();
List<Person> people = response.getConnections();
 
people = people_service.people().connections()
    .list('people/me', personFields='names,emailAddresses')
 
$people = $people_service->people_connections->listPeopleConnections(
    'people/me', array('personFields' => 'names,emailAddresses'));
 
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

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

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

البروتوكولJava
// 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
 
// 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();

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

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

البروتوكولJava
POST /v1/people:createContact HTTP/1.1
Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] }
Host: people.googleapis.com
 
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 في الشخص الذي تريد تعديل جهة اتصاله للتأكّد من أنّ جهة الاتصال لم تتغيّر منذ آخر قراءة. استخدِم الرمز التالي:

البروتوكولJava
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
 
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 طلبات كتابة مهمة (عمليات إنشاء جهات الاتصال وتعديلها)
  • عمليات كتابة جهات الاتصال اليومية (إجمالي)

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

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

البروتوكولJava
DELETE /v1/resource_name:deleteContact HTTP/1.1
Host: people.googleapis.com
 
peopleService.people().deleteContact("resource_name").execute();

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

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

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

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

البروتوكولJava
POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1
Body: {
  "contacts": [
    {
      "contactPerson": {
        "names": [
          {
            "givenName": "John",
            "familyName": "Doe"
          }
        ]
      }
    }
  ]
}
Host: people.googleapis.com
 
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 في كل جهة اتصال подлежат تعديلها للتأكّد من أنّ جهة الاتصال لم تتغيّر منذ المرة الأخيرة التي تمت فيها قراءة الملف. استخدِم الرمز التالي:

البروتوكولJava
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
 
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 عملية كتابة لجهات الاتصال يوميًا (إجمالي)

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

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

البروتوكولJava
POST /v1/people:batchDeleteContacts HTTP/1.1
Body: {"resource_names": ["resource_name"]}
Host: people.googleapis.com
 
BatchDeleteContactsRequest request = new BatchDeleteContactsRequest();

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

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

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

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