Google Contacts API в Delphi. Чтение и обновление имени контакта.

Сегодня затронем ещё один момент по работе с Google API в Delphi, а именно — посмотрим как необходимо правильно обновлять имя контакта.
Узнать имя контакта можно двумя способами:

1. Через содержимое узла title. При этом значение узла может собержать как полное имя, например, «Иванов Иван Иванович», так и сокращенные вариант (только имя, только фамилия, фамилия и инициалы и т.д.)
2. Через значения, содержащиеся в дочерних узлах gd:name. gd:name содержит структурированную информацию по контакту, такую как имя, фамилия, отчество и дополнительные элементы, такие как префик имени и т.д.

В данных о контакте элемент gd:name может отсутствовать.

Как может показаться на первый взгляд, наиболее просто и быстро узнать имя контакта, просто прочитав значение title и присвоив его какой-нибудь переменной. Однако на деле при таком подходе все может оказаться не так просто и гладко.
Дело в том, что если мы захотим обновиться имя контакта, то нам в любом случае необходим узел gd:name в отпраляемом документа. При выполнении PUT-запроса на обновление данных Google обновляет данные по следующей (примерной) схеме:
1. Проверяется валидность XML-докумена, если документ содержит ошибки обновление не производится.
2. Обновляется каждое поле контакта. При этом, если в XML-документе, содержатся «лишние» узлы, например, link с даными об изображении, то такие узлы просто игнорируются.
3. Если XML содержит узел gd:name, то вначале вносятся изменения имени контакта, а затем содержимое этого узла дублируется в узле title ответного документа.
В этой же схеме «лишним» оказывается и узел title. Проверить это можно достаточно просто. Берем контакт, например, такой:

<entry>
<id>http://www.google.com/m8/feeds/contacts/vlad383%40gmail.com/base/54cbb4f68a234171</id>
<updated>2010-07-02T08:56:03.938Z</updated>
<category scheme=»http://schemas.google.com/g/2005#kind» term=»http://schemas.google.com/contact/2008#contact» />
<title>Иванов Иван Иванович</title>
<content>Примечание</content>
<gd:name>
<gd:fullName>Иванов Иван Иванович</gd:fullName>
<gd:givenName>Иванов</gd:givenName>
<gd:additionalName>Иван</gd:additionalName>
<gd:familyName>Иванович</gd:familyName>
</gd:name>
<gContact:nickname>Vanusha</gContact:nickname>
<gContact:birthday when=»1983-05-02″ />
<gd:email rel=»http://schemas.google.com/g/2005#other» address=»vanya@gmail.com» primary=»true» />
</entry>

Как видите, контакт содержит и title и gd:name. Пробуем изменить имя контакта с помощью узла title — для этого формируем такой документ:

<entry>
<id>http://www.google.com/m8/feeds/contacts/vlad383%40gmail.com/base/54cbb4f68a234171</id>
<updated>2010-07-02T08:56:03.938Z</updated>
<category scheme=»http://schemas.google.com/g/2005#kind» term=»http://schemas.google.com/contact/2008#contact» />
<title>Новое имя контакта</title>
<content>Примечание</content>
<gd:name>
<gContact:nickname>Vanusha</gContact:nickname>
<gContact:birthday when=»1983-05-02″ />
<gd:email rel=»http://schemas.google.com/g/2005#other» address=»vanya@gmail.com» primary=»true» />
</entry>

И отправляем этот документ на сервер, используя PUT-запрос. Ответный документ будет таким:

<entry>
<id>http://www.google.com/m8/feeds/contacts/vlad383%40gmail.com/base/54cbb4f68a234171</id>
<updated>2010-07-02T08:56:03.938Z</updated>
<category scheme=»http://schemas.google.com/g/2005#kind» term=»http://schemas.google.com/contact/2008#contact» />
<title/>
<content>Примечание</content>
<gd:name>
<gContact:nickname>Vanusha</gContact:nickname>
<gContact:birthday when=»1983-05-02″ />
<gd:email rel=»http://schemas.google.com/g/2005#other» address=»vanya@gmail.com» primary=»true» />
</entry>

Что и требовалось доказать — title в отправляемом нами документе проигнорировался. Правильным был бы такой документ:

<entry>
<id>http://www.google.com/m8/feeds/contacts/vlad383%40gmail.com/base/54cbb4f68a234171</id>
<updated>2010-07-02T08:56:03.938Z</updated>
<category scheme=»http://schemas.google.com/g/2005#kind» term=»http://schemas.google.com/contact/2008#contact» />
<content>Примечание</content>
<gd:name>
<gd:fullName>New User</gd:fullName>
<gd:givenName>User</gd:givenName>
<gd:familyName>New</gd:familyName>
</gd:name>
<gContact:nickname>Vanusha</gContact:nickname>
<gContact:birthday when=»1983-05-02″ />
<gd:email rel=»http://schemas.google.com/g/2005#other» address=»vanya@gmail.com» primary=»true» />
</entry>

В этом случае имя контакта полностью будет изменено, а ответный документ будет содержать узел title и измененный gd:name.

В общем случае узел gd:name может содержать следующую информацию (в дочерних узлах):

1. gd: GivenName — имя
2. gd:additionalName — дополнительное имя, в нашем случае — отчество
3. gd:familyName — фамилия
4. gd: namePrefix — префикс, например, «Мистер»
5. gd: nameSuffix — суфикс, например «III» или «Сан»
6. gd:fullName — неструктурированное полное имя, например «Иванов Иван Иванович»

Любой из этих элементов может отсутствовать. В целом, при работе с именами контактов в Google Contacts API можно придерживаться следующей схемы:

1. Получаем XML-документ с информацией о контакте
2. Если контакт содержит узел gd:name, то парсим его содержимое и составляем имя контакта, иначе пробуем прочиать title.
3. Если документ содержит только title, то:
   1. Принимаем за имя контакта значение title
   2. При обновлении обязательно включаем gd:name в документ. Если имя контакта было взято из title, то во избежание лишних проблем это имя следует записать в gd:name —>gd:fullName.

Ну и последнее, что хотелось бы отметить в плане работы с Google API, так это то, что никогда не следует забывать, что имена узлов чувствительны к регистру. Например узел gd:NaMe будет проигнорирован при обработке запроса.

Книжная полка

	Автор: Андрей Шкрыль Название: Разработка клиент-серверных приложений в Delphi Описание: Рассмотрены практические вопросы по разработке клиент-серверных приложений в среде Delphi 7 и Delphi 2005 с использованием СУБД MS SQL Server 2000, InterBase и Firebird. Приведена информация о теории построения реляционных баз данных и языке SQL. Освещены вопросы эксплуатации и администрирования СУБД.
	Автор: Антон Григорьев Название: О чем не пишут в книгах по Delphi Описание: Рассмотрены малоосвещенные вопросы программирования в Delphi. Описаны методы интеграции VCL и API. Показаны внутренние механизмы VCL и приведены примеры вмешательства в эти механизмы. Рассмотрено использование сокетов в Delphi: различные режимы их работы, особенности для протоколов TCP и UDP и др.