1<?php 2/* 3 * Copyright 2014 Google Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); you may not 6 * use this file except in compliance with the License. You may obtain a copy of 7 * the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 14 * License for the specific language governing permissions and limitations under 15 * the License. 16 */ 17 18namespace Google\Service\PeopleService\Resource; 19 20use Google\Service\PeopleService\BatchCreateContactsRequest; 21use Google\Service\PeopleService\BatchCreateContactsResponse; 22use Google\Service\PeopleService\BatchDeleteContactsRequest; 23use Google\Service\PeopleService\BatchUpdateContactsRequest; 24use Google\Service\PeopleService\BatchUpdateContactsResponse; 25use Google\Service\PeopleService\DeleteContactPhotoResponse; 26use Google\Service\PeopleService\GetPeopleResponse; 27use Google\Service\PeopleService\ListDirectoryPeopleResponse; 28use Google\Service\PeopleService\PeopleEmpty; 29use Google\Service\PeopleService\Person; 30use Google\Service\PeopleService\SearchDirectoryPeopleResponse; 31use Google\Service\PeopleService\SearchResponse; 32use Google\Service\PeopleService\UpdateContactPhotoRequest; 33use Google\Service\PeopleService\UpdateContactPhotoResponse; 34 35/** 36 * The "people" collection of methods. 37 * Typical usage is: 38 * <code> 39 * $peopleService = new Google\Service\PeopleService(...); 40 * $people = $peopleService->people; 41 * </code> 42 */ 43class People extends \Google\Service\Resource 44{ 45 /** 46 * Create a batch of new contacts and return the PersonResponses for the newly 47 * Mutate requests for the same user should be sent sequentially to avoid 48 * increased latency and failures. (people.batchCreateContacts) 49 * 50 * @param BatchCreateContactsRequest $postBody 51 * @param array $optParams Optional parameters. 52 * @return BatchCreateContactsResponse 53 */ 54 public function batchCreateContacts(BatchCreateContactsRequest $postBody, $optParams = []) 55 { 56 $params = ['postBody' => $postBody]; 57 $params = array_merge($params, $optParams); 58 return $this->call('batchCreateContacts', [$params], BatchCreateContactsResponse::class); 59 } 60 /** 61 * Delete a batch of contacts. Any non-contact data will not be deleted. Mutate 62 * requests for the same user should be sent sequentially to avoid increased 63 * latency and failures. (people.batchDeleteContacts) 64 * 65 * @param BatchDeleteContactsRequest $postBody 66 * @param array $optParams Optional parameters. 67 * @return PeopleEmpty 68 */ 69 public function batchDeleteContacts(BatchDeleteContactsRequest $postBody, $optParams = []) 70 { 71 $params = ['postBody' => $postBody]; 72 $params = array_merge($params, $optParams); 73 return $this->call('batchDeleteContacts', [$params], PeopleEmpty::class); 74 } 75 /** 76 * Update a batch of contacts and return a map of resource names to 77 * PersonResponses for the updated contacts. Mutate requests for the same user 78 * should be sent sequentially to avoid increased latency and failures. 79 * (people.batchUpdateContacts) 80 * 81 * @param BatchUpdateContactsRequest $postBody 82 * @param array $optParams Optional parameters. 83 * @return BatchUpdateContactsResponse 84 */ 85 public function batchUpdateContacts(BatchUpdateContactsRequest $postBody, $optParams = []) 86 { 87 $params = ['postBody' => $postBody]; 88 $params = array_merge($params, $optParams); 89 return $this->call('batchUpdateContacts', [$params], BatchUpdateContactsResponse::class); 90 } 91 /** 92 * Create a new contact and return the person resource for that contact. The 93 * request returns a 400 error if more than one field is specified on a field 94 * that is a singleton for contact sources: * biographies * birthdays * genders 95 * * names Mutate requests for the same user should be sent sequentially to 96 * avoid increased latency and failures. (people.createContact) 97 * 98 * @param Person $postBody 99 * @param array $optParams Optional parameters. 100 * 101 * @opt_param string personFields Required. A field mask to restrict which 102 * fields on each person are returned. Multiple fields can be specified by 103 * separating them with commas. Defaults to all fields if not set. Valid values 104 * are: * addresses * ageRanges * biographies * birthdays * calendarUrls * 105 * clientData * coverPhotos * emailAddresses * events * externalIds * genders * 106 * imClients * interests * locales * locations * memberships * metadata * 107 * miscKeywords * names * nicknames * occupations * organizations * phoneNumbers 108 * * photos * relations * sipAddresses * skills * urls * userDefined 109 * @opt_param string sources Optional. A mask of what source types to return. 110 * Defaults to READ_SOURCE_TYPE_CONTACT and READ_SOURCE_TYPE_PROFILE if not set. 111 * @return Person 112 */ 113 public function createContact(Person $postBody, $optParams = []) 114 { 115 $params = ['postBody' => $postBody]; 116 $params = array_merge($params, $optParams); 117 return $this->call('createContact', [$params], Person::class); 118 } 119 /** 120 * Delete a contact person. Any non-contact data will not be deleted. Mutate 121 * requests for the same user should be sent sequentially to avoid increased 122 * latency and failures. (people.deleteContact) 123 * 124 * @param string $resourceName Required. The resource name of the contact to 125 * delete. 126 * @param array $optParams Optional parameters. 127 * @return PeopleEmpty 128 */ 129 public function deleteContact($resourceName, $optParams = []) 130 { 131 $params = ['resourceName' => $resourceName]; 132 $params = array_merge($params, $optParams); 133 return $this->call('deleteContact', [$params], PeopleEmpty::class); 134 } 135 /** 136 * Delete a contact's photo. Mutate requests for the same user should be done 137 * sequentially to avoid // lock contention. (people.deleteContactPhoto) 138 * 139 * @param string $resourceName Required. The resource name of the contact whose 140 * photo will be deleted. 141 * @param array $optParams Optional parameters. 142 * 143 * @opt_param string personFields Optional. A field mask to restrict which 144 * fields on the person are returned. Multiple fields can be specified by 145 * separating them with commas. Defaults to empty if not set, which will skip 146 * the post mutate get. Valid values are: * addresses * ageRanges * biographies 147 * * birthdays * calendarUrls * clientData * coverPhotos * emailAddresses * 148 * events * externalIds * genders * imClients * interests * locales * locations 149 * * memberships * metadata * miscKeywords * names * nicknames * occupations * 150 * organizations * phoneNumbers * photos * relations * sipAddresses * skills * 151 * urls * userDefined 152 * @opt_param string sources Optional. A mask of what source types to return. 153 * Defaults to READ_SOURCE_TYPE_CONTACT and READ_SOURCE_TYPE_PROFILE if not set. 154 * @return DeleteContactPhotoResponse 155 */ 156 public function deleteContactPhoto($resourceName, $optParams = []) 157 { 158 $params = ['resourceName' => $resourceName]; 159 $params = array_merge($params, $optParams); 160 return $this->call('deleteContactPhoto', [$params], DeleteContactPhotoResponse::class); 161 } 162 /** 163 * Provides information about a person by specifying a resource name. Use 164 * `people/me` to indicate the authenticated user. The request returns a 400 165 * error if 'personFields' is not specified. (people.get) 166 * 167 * @param string $resourceName Required. The resource name of the person to 168 * provide information about. - To get information about the authenticated user, 169 * specify `people/me`. - To get information about a google account, specify 170 * `people/{account_id}`. - To get information about a contact, specify the 171 * resource name that identifies the contact as returned by 172 * `people.connections.list`. 173 * @param array $optParams Optional parameters. 174 * 175 * @opt_param string personFields Required. A field mask to restrict which 176 * fields on the person are returned. Multiple fields can be specified by 177 * separating them with commas. Valid values are: * addresses * ageRanges * 178 * biographies * birthdays * calendarUrls * clientData * coverPhotos * 179 * emailAddresses * events * externalIds * genders * imClients * interests * 180 * locales * locations * memberships * metadata * miscKeywords * names * 181 * nicknames * occupations * organizations * phoneNumbers * photos * relations * 182 * sipAddresses * skills * urls * userDefined 183 * @opt_param string requestMask.includeField Required. Comma-separated list of 184 * person fields to be included in the response. Each path should start with 185 * `person.`: for example, `person.names` or `person.photos`. 186 * @opt_param string sources Optional. A mask of what source types to return. 187 * Defaults to READ_SOURCE_TYPE_PROFILE and READ_SOURCE_TYPE_CONTACT if not set. 188 * @return Person 189 */ 190 public function get($resourceName, $optParams = []) 191 { 192 $params = ['resourceName' => $resourceName]; 193 $params = array_merge($params, $optParams); 194 return $this->call('get', [$params], Person::class); 195 } 196 /** 197 * Provides information about a list of specific people by specifying a list of 198 * requested resource names. Use `people/me` to indicate the authenticated user. 199 * The request returns a 400 error if 'personFields' is not specified. 200 * (people.getBatchGet) 201 * 202 * @param array $optParams Optional parameters. 203 * 204 * @opt_param string personFields Required. A field mask to restrict which 205 * fields on each person are returned. Multiple fields can be specified by 206 * separating them with commas. Valid values are: * addresses * ageRanges * 207 * biographies * birthdays * calendarUrls * clientData * coverPhotos * 208 * emailAddresses * events * externalIds * genders * imClients * interests * 209 * locales * locations * memberships * metadata * miscKeywords * names * 210 * nicknames * occupations * organizations * phoneNumbers * photos * relations * 211 * sipAddresses * skills * urls * userDefined 212 * @opt_param string requestMask.includeField Required. Comma-separated list of 213 * person fields to be included in the response. Each path should start with 214 * `person.`: for example, `person.names` or `person.photos`. 215 * @opt_param string resourceNames Required. The resource names of the people to 216 * provide information about. It's repeatable. The URL query parameter should be 217 * resourceNames==&... - To get information about the authenticated user, 218 * specify `people/me`. - To get information about a google account, specify 219 * `people/{account_id}`. - To get information about a contact, specify the 220 * resource name that identifies the contact as returned by 221 * `people.connections.list`. There is a maximum of 200 resource names. 222 * @opt_param string sources Optional. A mask of what source types to return. 223 * Defaults to READ_SOURCE_TYPE_CONTACT and READ_SOURCE_TYPE_PROFILE if not set. 224 * @return GetPeopleResponse 225 */ 226 public function getBatchGet($optParams = []) 227 { 228 $params = []; 229 $params = array_merge($params, $optParams); 230 return $this->call('getBatchGet', [$params], GetPeopleResponse::class); 231 } 232 /** 233 * Provides a list of domain profiles and domain contacts in the authenticated 234 * user's domain directory. When the `sync_token` is specified, resources 235 * deleted since the last sync will be returned as a person with 236 * `PersonMetadata.deleted` set to true. When the `page_token` or `sync_token` 237 * is specified, all other request parameters must match the first call. Writes 238 * may have a propagation delay of several minutes for sync requests. 239 * Incremental syncs are not intended for read-after-write use cases. See 240 * example usage at [List the directory people that have 241 * changed](/people/v1/directory#list_the_directory_people_that_have_changed). 242 * (people.listDirectoryPeople) 243 * 244 * @param array $optParams Optional parameters. 245 * 246 * @opt_param string mergeSources Optional. Additional data to merge into the 247 * directory sources if they are connected through verified join keys such as 248 * email addresses or phone numbers. 249 * @opt_param int pageSize Optional. The number of people to include in the 250 * response. Valid values are between 1 and 1000, inclusive. Defaults to 100 if 251 * not set or set to 0. 252 * @opt_param string pageToken Optional. A page token, received from a previous 253 * response `next_page_token`. Provide this to retrieve the subsequent page. 254 * When paginating, all other parameters provided to 255 * `people.listDirectoryPeople` must match the first call that provided the page 256 * token. 257 * @opt_param string readMask Required. A field mask to restrict which fields on 258 * each person are returned. Multiple fields can be specified by separating them 259 * with commas. Valid values are: * addresses * ageRanges * biographies * 260 * birthdays * calendarUrls * clientData * coverPhotos * emailAddresses * events 261 * * externalIds * genders * imClients * interests * locales * locations * 262 * memberships * metadata * miscKeywords * names * nicknames * occupations * 263 * organizations * phoneNumbers * photos * relations * sipAddresses * skills * 264 * urls * userDefined 265 * @opt_param bool requestSyncToken Optional. Whether the response should return 266 * `next_sync_token`. It can be used to get incremental changes since the last 267 * request by setting it on the request `sync_token`. More details about sync 268 * behavior at `people.listDirectoryPeople`. 269 * @opt_param string sources Required. Directory sources to return. 270 * @opt_param string syncToken Optional. A sync token, received from a previous 271 * response `next_sync_token` Provide this to retrieve only the resources 272 * changed since the last request. When syncing, all other parameters provided 273 * to `people.listDirectoryPeople` must match the first call that provided the 274 * sync token. More details about sync behavior at `people.listDirectoryPeople`. 275 * @return ListDirectoryPeopleResponse 276 */ 277 public function listDirectoryPeople($optParams = []) 278 { 279 $params = []; 280 $params = array_merge($params, $optParams); 281 return $this->call('listDirectoryPeople', [$params], ListDirectoryPeopleResponse::class); 282 } 283 /** 284 * Provides a list of contacts in the authenticated user's grouped contacts that 285 * matches the search query. The query matches on a contact's `names`, 286 * `nickNames`, `emailAddresses`, `phoneNumbers`, and `organizations` fields 287 * that are from the CONTACT source. **IMPORTANT**: Before searching, clients 288 * should send a warmup request with an empty query to update the cache. See 289 * https://developers.google.com/people/v1/contacts#search_the_users_contacts 290 * (people.searchContacts) 291 * 292 * @param array $optParams Optional parameters. 293 * 294 * @opt_param int pageSize Optional. The number of results to return. Defaults 295 * to 10 if field is not set, or set to 0. Values greater than 30 will be capped 296 * to 30. 297 * @opt_param string query Required. The plain-text query for the request. The 298 * query is used to match prefix phrases of the fields on a person. For example, 299 * a person with name "foo name" matches queries such as "f", "fo", "foo", "foo 300 * n", "nam", etc., but not "oo n". 301 * @opt_param string readMask Required. A field mask to restrict which fields on 302 * each person are returned. Multiple fields can be specified by separating them 303 * with commas. Valid values are: * addresses * ageRanges * biographies * 304 * birthdays * calendarUrls * clientData * coverPhotos * emailAddresses * events 305 * * externalIds * genders * imClients * interests * locales * locations * 306 * memberships * metadata * miscKeywords * names * nicknames * occupations * 307 * organizations * phoneNumbers * photos * relations * sipAddresses * skills * 308 * urls * userDefined 309 * @opt_param string sources Optional. A mask of what source types to return. 310 * Defaults to READ_SOURCE_TYPE_CONTACT if not set. 311 * @return SearchResponse 312 */ 313 public function searchContacts($optParams = []) 314 { 315 $params = []; 316 $params = array_merge($params, $optParams); 317 return $this->call('searchContacts', [$params], SearchResponse::class); 318 } 319 /** 320 * Provides a list of domain profiles and domain contacts in the authenticated 321 * user's domain directory that match the search query. 322 * (people.searchDirectoryPeople) 323 * 324 * @param array $optParams Optional parameters. 325 * 326 * @opt_param string mergeSources Optional. Additional data to merge into the 327 * directory sources if they are connected through verified join keys such as 328 * email addresses or phone numbers. 329 * @opt_param int pageSize Optional. The number of people to include in the 330 * response. Valid values are between 1 and 500, inclusive. Defaults to 100 if 331 * not set or set to 0. 332 * @opt_param string pageToken Optional. A page token, received from a previous 333 * response `next_page_token`. Provide this to retrieve the subsequent page. 334 * When paginating, all other parameters provided to `SearchDirectoryPeople` 335 * must match the first call that provided the page token. 336 * @opt_param string query Required. Prefix query that matches fields in the 337 * person. Does NOT use the read_mask for determining what fields to match. 338 * @opt_param string readMask Required. A field mask to restrict which fields on 339 * each person are returned. Multiple fields can be specified by separating them 340 * with commas. Valid values are: * addresses * ageRanges * biographies * 341 * birthdays * calendarUrls * clientData * coverPhotos * emailAddresses * events 342 * * externalIds * genders * imClients * interests * locales * locations * 343 * memberships * metadata * miscKeywords * names * nicknames * occupations * 344 * organizations * phoneNumbers * photos * relations * sipAddresses * skills * 345 * urls * userDefined 346 * @opt_param string sources Required. Directory sources to return. 347 * @return SearchDirectoryPeopleResponse 348 */ 349 public function searchDirectoryPeople($optParams = []) 350 { 351 $params = []; 352 $params = array_merge($params, $optParams); 353 return $this->call('searchDirectoryPeople', [$params], SearchDirectoryPeopleResponse::class); 354 } 355 /** 356 * Update contact data for an existing contact person. Any non-contact data will 357 * not be modified. Any non-contact data in the person to update will be 358 * ignored. All fields specified in the `update_mask` will be replaced. The 359 * server returns a 400 error if `person.metadata.sources` is not specified for 360 * the contact to be updated or if there is no contact source. The server 361 * returns a 400 error with reason `"failedPrecondition"` if 362 * `person.metadata.sources.etag` is different than the contact's etag, which 363 * indicates the contact has changed since its data was read. Clients should get 364 * the latest person and merge their updates into the latest person. The server 365 * returns a 400 error if `memberships` are being updated and there are no 366 * contact group memberships specified on the person. The server returns a 400 367 * error if more than one field is specified on a field that is a singleton for 368 * contact sources: * biographies * birthdays * genders * names Mutate requests 369 * for the same user should be sent sequentially to avoid increased latency and 370 * failures. (people.updateContact) 371 * 372 * @param string $resourceName The resource name for the person, assigned by the 373 * server. An ASCII string with a max length of 27 characters, in the form of 374 * `people/{person_id}`. 375 * @param Person $postBody 376 * @param array $optParams Optional parameters. 377 * 378 * @opt_param string personFields Optional. A field mask to restrict which 379 * fields on each person are returned. Multiple fields can be specified by 380 * separating them with commas. Defaults to all fields if not set. Valid values 381 * are: * addresses * ageRanges * biographies * birthdays * calendarUrls * 382 * clientData * coverPhotos * emailAddresses * events * externalIds * genders * 383 * imClients * interests * locales * locations * memberships * metadata * 384 * miscKeywords * names * nicknames * occupations * organizations * phoneNumbers 385 * * photos * relations * sipAddresses * skills * urls * userDefined 386 * @opt_param string sources Optional. A mask of what source types to return. 387 * Defaults to READ_SOURCE_TYPE_CONTACT and READ_SOURCE_TYPE_PROFILE if not set. 388 * @opt_param string updatePersonFields Required. A field mask to restrict which 389 * fields on the person are updated. Multiple fields can be specified by 390 * separating them with commas. All updated fields will be replaced. Valid 391 * values are: * addresses * biographies * birthdays * calendarUrls * clientData 392 * * emailAddresses * events * externalIds * genders * imClients * interests * 393 * locales * locations * memberships * miscKeywords * names * nicknames * 394 * occupations * organizations * phoneNumbers * relations * sipAddresses * urls 395 * * userDefined 396 * @return Person 397 */ 398 public function updateContact($resourceName, Person $postBody, $optParams = []) 399 { 400 $params = ['resourceName' => $resourceName, 'postBody' => $postBody]; 401 $params = array_merge($params, $optParams); 402 return $this->call('updateContact', [$params], Person::class); 403 } 404 /** 405 * Update a contact's photo. Mutate requests for the same user should be sent 406 * sequentially to avoid increased latency and failures. 407 * (people.updateContactPhoto) 408 * 409 * @param string $resourceName Required. Person resource name 410 * @param UpdateContactPhotoRequest $postBody 411 * @param array $optParams Optional parameters. 412 * @return UpdateContactPhotoResponse 413 */ 414 public function updateContactPhoto($resourceName, UpdateContactPhotoRequest $postBody, $optParams = []) 415 { 416 $params = ['resourceName' => $resourceName, 'postBody' => $postBody]; 417 $params = array_merge($params, $optParams); 418 return $this->call('updateContactPhoto', [$params], UpdateContactPhotoResponse::class); 419 } 420} 421 422// Adding a class alias for backwards compatibility with the previous class name. 423class_alias(People::class, 'Google_Service_PeopleService_Resource_People'); 424