Руководство разработчика: PHP

API данных Blogger позволяет клиентским приложениям просматривать и обновлять контент Blogger в виде каналов API данных Google.

Ваше клиентское приложение может использовать API данных Blogger для создания новых сообщений в блоге, редактирования или удаления существующих сообщений в блоге, а также для запроса сообщений в блоге, соответствующих определенным критериям.

Помимо общей информации о возможностях Blogger Data API, в этом документе приводятся примеры базового взаимодействия Data API с использованием клиентской библиотеки Zend Google Data API . Если вы хотите узнать больше о базовом протоколе, который использует библиотека, см. раздел «Протокол» данного руководства для разработчиков.

Содержание

  1. Аудитория
  2. Начиная
    1. Создание учетной записи Blogger
    2. Запуск примера кода
    3. Использование магических геттеров и сеттеров
    4. Другие источники
  3. Аутентификация в сервисе Blogger
    1. аутентификация OAuth
    2. Аутентификация прокси-сервера AuthSub
    3. Аутентификация по имени пользователя и паролю ClientLogin
  4. Получение списка блогов
  5. Создание постов
    1. Публикация сообщения в блоге
    2. Создание черновика публикации в блоге
  6. Получение сообщений
    1. Получение всех сообщений блога
    2. Получение сообщений с использованием параметров запроса
  7. Обновление сообщений
  8. Удаление сообщений
  9. Комментарии
    1. Создание комментариев
    2. Получение комментариев
    3. Удаление комментариев

Аудитория

Этот документ предназначен для программистов, желающих писать клиентские приложения PHP, способные взаимодействовать с Blogger.

В этом документе предполагается, что вы понимаете общие идеи протокола API данных Google .

Справочную информацию о классах и методах, предоставляемых клиентской библиотекой, см. в справочнике по API клиентской библиотеки PHP . Общую справочную информацию по API данных Blogger см. в справочном руководстве по протоколу .

Начиная

Для получения помощи по настройке клиентской библиотеки см. Руководство по началу работы .

Клиентская библиотека Zend требует PHP 5.1.4 или более поздней версии. Он доступен как часть Zend Framework , а также как отдельная загрузка . Для взаимодействия с Blogger используйте клиентскую библиотеку версии 1.0.0 или более поздней.

Создание учетной записи Blogger

Возможно, вы захотите зарегистрировать учетную запись Blogger в целях тестирования. Blogger использует учетные записи Google , поэтому, если у вас уже есть учетная запись Google, все готово.

Запуск примера кода

Полноценный рабочий образец клиента, содержащий весь пример кода, показанный в этом документе, доступен в репозитории Zend Framework SVN . Образец находится по адресу /framework/standard/trunk/demos/Zend/Gdata/Blogger.php . Образец содержит все функции, описанные в этом документе. Его можно запустить только из командной строки:

php Blogger.php -- --user=[email_address] --pass=[password]

Прежде чем запускать этот пример или разрабатывать собственный код с использованием Zend Framework, вам может потребоваться установить include_path и загрузить соответствующие классы. Путь включения можно установить либо с помощью настройки php.ini , либо с помощью метода set_include_path . Этот код запрашивает доступ к основному классу Zend_Gdata , классу Zend_Gdata_Query и классу аутентификации Zend_Gdata_ClientLogin .

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_Query');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');

Использование магических геттеров и сеттеров

В клиентскую библиотеку PHP для удобства разработчиков добавлена ​​поддержка магических сеттеров/геттеров . Они позволяют безопасно получать доступ к свойствам класса с помощью традиционных методов установки/получания или путем доступа к свойствам. Например, если $gdataObject является экземпляром объекта в этой библиотеке, то следующие две строки кода будут иметь одинаковый эффект:

$gdataObject->setFoo("bar");
$gdataObject->foo = "bar";

Аналогично, эти две строки кода также имеют одинаковый эффект:

$baz = $gdataObject->getFoo();
$baz = $gdataObject->foo;

Аналогично, магические фабричные методы упрощают объявление новых объектов. Вместо того, чтобы запоминать длинные имена классов, предусмотренные соглашением об именах Zend, вы можете создать новый object , вызвав newObject(); на клиенте службы Zend. Например, в следующих двух фрагментах объявлен новый объект расширения draft . Дополнительную информацию о drafts вы найдете в разделе создания публикации .

// Traditional instantiation
$gdClient = new Zend_Gdata();
$draft = new Zend_Gdata_App_Extension_Draft();

// Magic factory instantiation
$gdClient = new Zend_Gdata();
$draft = $gdClient->newDraft();

Магические сеттеры/геттеры и фабрики не являются обязательными, поэтому используйте тот подход, который вам больше подходит.

Другие источники

Другие ресурсы для компонента API данных Google Zend Framework (Zend_Gdata):

Аутентификация в службе Blogger

Вы можете получить доступ как к общедоступным, так и к частным каналам с помощью API данных Blogger. Публичные каналы не требуют аутентификации, но доступны только для чтения. Если вы хотите изменить блоги, вашему клиенту необходимо пройти аутентификацию перед запросом частных каналов. Он может аутентифицироваться с использованием любого из трех подходов: аутентификация OAuth , аутентификация прокси-сервера AuthSub или аутентификация по имени пользователя и паролю ClientLogin .

Дополнительную информацию об аутентификации с помощью API данных Google в целом см. в документации по аутентификации .

В большинстве примеров в последующих разделах этого документа предполагается, что у вас есть аутентифицированный клиентский объект с именем $gdClient .

аутентификация OAuth

Документацию по аутентификации OAuth с использованием библиотеки Zend PHP GData см. в разделе OAuth в клиентских библиотеках протокола данных Google .

Аутентификация прокси-сервера AuthSub

Аутентификация прокси-сервера AuthSub используется веб-приложениями, которым необходимо аутентифицировать своих пользователей в учетных записях Google. Оператор веб-сайта и клиентский код не имеют доступа к имени пользователя и паролю пользователя Blogger; вместо этого клиент получает специальные токены AuthSub, которые позволяют клиенту действовать от имени конкретного пользователя. Более подробную информацию смотрите в документации AuthSub .

Когда пользователь впервые посещает ваше приложение, он еще не прошел аутентификацию. В этом случае вам необходимо отобразить некоторую информацию и ссылку, направляющую пользователя на страницу Google для подтверждения вашего запроса на доступ к их блогам. Клиентская библиотека Zend предоставляет функцию для генерации URL-адреса страницы Google. Код ниже получает URL-адрес страницы AuthSubRequest:

function getAuthSubUrl()
{
  $next = getCurrentUrl();
  $scope = 'http://www.google.com/blogger/feeds/';
  $secure = false;
  $session = true;
  return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure, $session);
}

$authSubUrl = getAuthSubUrl();
echo '<a href=\"$authSubUrl\">login to your Google account</a>';

Метод getAuthSubTokenUri принимает следующие параметры (соответствующие параметрам запроса, используемым обработчиком AuthSubRequest):

следующий
URL-адрес страницы, на которую Google должен перенаправить пользователя после аутентификации.
объем
Указывает, что приложение запрашивает токен для доступа к каналам Blogger. Используемая строка области действия — http://www.blogger.com/feeds/ (разумеется, в URL-кодировке).
безопасный
Указывает, запрашивает ли клиент безопасный токен.
сессия
Указывает, можно ли обменять возвращенный токен на многоразовый (сессионный) токен.

В приведенном выше примере показан вызов, который не запрашивает маркер безопасности (значение secure — false ). Результирующий URL-адрес запроса может выглядеть следующим образом:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.php

Пользователь переходит по ссылке на сайт Google и авторизуется в своей учетной записи Google.

После аутентификации пользователя система AuthSub перенаправляет его на URL-адрес, указанный в next параметре запроса URL-адреса AuthSubRequest. Система AuthSub добавляет токен аутентификации к этому URL-адресу в качестве значения параметра запроса token . Например:

http://www.example.com/welcome.php?token=yourAuthToken

Вы можете получить значение токена, используя $_GET['token'] .

Это значение токена представляет собой одноразовый токен AuthSub. В этом примере, поскольку было указано $session = true , этот токен можно обменять на токен сеанса AuthSub с помощью метода Zend_Gdata_AuthSub::getAuthSubSessionToken , который вызывает сервис AuthSubSessionToken :

if(! isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
  $_SESSION['sessionToken'] =
      Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
}

Фрагмент кода сначала проверяет, присутствует ли уже токен сеанса AuthSub. Если это не так, но в URL-адресе указан одноразовый токен, то фрагмент кода передает одноразовый токен методу getAuthSubSessionToken , а интерфейс AuthSub возвращает токен сеанса. Затем код помещает значение токена сеанса в переменную сеанса $_SESSION['sessionToken'] .

Затем ваше приложение сможет использовать значение токена сеанса при последующем взаимодействии с Blogger. Вы можете использовать метод Zend_Gdata_AuthSub::getHttpClient чтобы получить объект Zend_Http_Client , который имеет предустановленный заголовок Authorization , включающий учетные данные AuthSub:

$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);

Аутентификация по имени пользователя и паролю ClientLogin

Используйте аутентификацию ClientLogin, если ваш клиент является автономным, однопользовательским «установленным» клиентом (например, настольным приложением).

Следующий код использует метод Zend_Gdata_ClientLogin::getHttpClient для выполнения запроса к службе ClientLogin, получения токена аутентификации и создания объекта Zend_Http_Client с соответствующим заголовком аутентификации. Затем HttpClient , возвращаемый этим методом, используется для создания объекта службы Zend_Gdata .

Обратите внимание, что для $accountType явно установлено значение GOOGLE . Если этот параметр не задан, пользователи G Suite не смогут успешно использовать Blogger API.

$user = 'user@example.com';
$pass = 'secretPasswd';
$service = 'blogger';

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service, null,
        Zend_Gdata_ClientLogin::DEFAULT_SOURCE, null, null,
        Zend_Gdata_ClientLogin::CLIENTLOGIN_URI, 'GOOGLE');
$gdClient = new Zend_Gdata($client);

Дополнительные сведения об аутентификации ClientLogin, включая примеры запросов и ответов, см. в документации по аутентификации для установленных приложений .

Примечание . Используйте один и тот же токен для всех запросов в данном сеансе; не приобретайте новый токен для каждого запроса Blogger.

Примечание . Как описано в документации ClientLogin, запрос аутентификации может завершиться неудачей и запросить запрос CAPTCHA. Если вы хотите, чтобы Google выдал и обработал запрос CAPTCHA, отправьте пользователя на https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (а не на URL-адрес обработки CAPTCHA, указанный в документации ClientLogin).

Получение списка блогов

API данных Blogger предоставляет канал, в котором перечислены блоги конкретного пользователя; этот канал известен как «метафид».

В следующем примере кода используется проверенный объект $gdClient для получения метаканала, а затем печатается заголовок каждого блога.

Класс Zend_Gdata_Query заботится о создании URL-адреса запроса. В этом случае никакой дополнительной работы выполнять не нужно, но полезность класса Query станет очевидной в разделе получения сообщений по параметрам запроса этого документа.

function printAllBlogs()
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/default/blogs');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

function printFeed($feed)
{
  $i = 0;
  foreach($feed->entries as $entry) {
    print $i ." ". $entry->title->text . "\n";
    $i++;
  }
}

Обратите внимание на URL-адрес, используемый методом getFeed . Это URL-адрес метафида по умолчанию; он возвращает список блогов для текущего аутентифицированного пользователя. Чтобы получить доступ к каналу для другого пользователя, вы можете указать идентификатор пользователя вместо default в URL-адресе метафида. Идентификатор пользователя — это строка цифр в конце URL-адреса профиля пользователя.

Фрагмент кода ниже демонстрирует, как извлечь идентификатор блога из канала. Идентификатор блога понадобится вам для выполнения операций создания, обновления и удаления записей и комментариев. Переменная $index указывает, какой блог в ленте блогов пользователя используется. Поле id имеет форму tag:blogger.com,1999:user-userID.blog- blogID , поэтому split по символу «-» помещает идентификатор блога в последний элемент результирующего массива.

$idText = split('-', $feed->entries[$index]->id->text);
$blogID = $idText[2];

Создание постов

API данных Blogger позволяет создавать и публиковать новые записи блога, а также создавать черновики записей.

Примечание . Установка собственного автора для сообщений в настоящее время не поддерживается. Все новые сообщения будут отображаться так, как если бы они были созданы пользователем, прошедшим аутентификацию в данный момент.

Публикация сообщения в блоге

Вы можете использовать клиентскую библиотеку PHP для публикации новых записей в блоге.

Сначала создайте экземпляр записи, представляющий сообщение в блоге. Затем вы можете установить заголовок, содержание и другие атрибуты сообщения в блоге. Наконец, вызовите метод insertEntry , чтобы вставить сообщение. Здесь вы можете увидеть работу волшебной фабрики с новыми объектами Zend_Gdata_Entry , Zend_Gdata_App_Extension_Title и Zend_Gdata_App_Extension_Content .

function createPublishedPost($title='Hello, world!', $content='I am blogging on the internet.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();
  $entry->title = $gdClient->newTitle($title);
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  $newPostID = $idText[2];

  return $newPostID;
}

Создание черновика публикации в блоге

Черновики сообщений создаются так же, как и публичные сообщения, но вам необходимо установить атрибут черновика объекта записи. Вы можете создать черновик сообщения в блоге, подобного приведенному выше, добавив выделенные строки:

function createDraftPost($title='Salutations, world!', $content='Hmm ... not quite right, must rework the title later.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();

  $entry->title = $gdClient->newTitle(trim($title));
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $control = $gdClient->newControl();
  $draft = $gdClient->newDraft('yes');
  $control->setDraft($draft);
  $entry->control = $control;

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  return $idText[2];
}

Во многом аналогично настройке заголовка или содержания сообщения вы создаете новые объекты Zend_Gdata_App_Extension_Control и Zend_Gdata_App_Extension_Draft и назначаете их атрибуту управления записи.

Вы можете превратить существующий черновик сообщения в блоге в опубликованное сообщение, получив черновик сообщения, установив для атрибута черновика значение no и затем обновив сообщение. Мы рассмотрим получение и обновление сообщений в следующих двух разделах.

Получение сообщений

В следующих разделах описывается, как получить список сообщений блога с параметрами запроса и без них.

Вы можете запросить общедоступный канал Blogger без аутентификации. Таким образом, вам не нужно задавать учетные данные или выполнять аутентификацию AuthSub перед получением сообщений из общедоступного блога.

Получение всех сообщений блога

Чтобы получить сообщения пользователя, вызовите тот же метод getFeed , который использовался для получения метафида блогов, но на этот раз отправьте URL-адрес канала сообщений блога:

function printAllPosts($gdClient, $blogID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Получение сообщений с использованием параметров запроса

API данных Blogger позволяет запрашивать набор записей, соответствующих заданным критериям, например запрос публикаций в блоге или обновлений в заданном диапазоне дат. Для этого вы создаете объект запроса и передаете его методу getFeed .

Например, чтобы отправить запрос диапазона дат, установите параметры published-min и published-max объекта запроса. Следующий фрагмент кода печатает заголовок и содержимое каждой записи блога, опубликованной между заданным временем начала и временем окончания:

function printPostsInDateRange($gdClient, $blogID, $startDate='2007-04-01', $endDate='2007-04-25')
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $query->setParam('published-min', $startDate);
  $query->setParam('published-max', $endDate);

  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Полезным методом отладки для класса Zend_Gdata_Query является getQueryUrl() , который покажет вам созданный закодированный URL-адрес.

Примечание . В настоящее время не существует магических установщиков для параметров запроса published-min и published-max . Однако вы можете использовать setStartIndex и setMaxResults .

API данных Blogger поддерживает следующие параметры запроса:

категории
Указывает категории (также известные как метки) для фильтрации результатов ленты. Например, http://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurie возвращает записи с метками Fritz и Laurie .
максимальные результаты
Максимальное количество возвращаемых записей.
опубликованный минимум, опубликованный максимум
Границы дат публикации записей.
стартовый индекс
Индекс первого результата, отсчитываемого от 1 (для разбиения по страницам).

Дополнительную информацию о параметрах запроса см. в Справочном руководстве по API данных Blogger и Справочном руководстве по API данных Google .

Обновление сообщений

Чтобы обновить существующую публикацию в блоге, сначала вы получаете запись, которую хотите обновить, затем изменяете ее, а затем отправляете ее в Blogger, используя метод save . Следующий фрагмент кода изменяет заголовок и содержимое записи блога, предполагая, что вы уже получили запись с сервера.

public function updatePost($postID, $updatedTitle='Hello, World?',
                           $updatedContent='UPDATE: Still blogging',
                           $isDraft=False)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID);
  $postToUpdate = $dClient->getEntry($query);
  $postToUpdate->title->text = $this->gdClient->newTitle($updatedTitle);
  $postToUpdate->content->text = $this->gdClient->newContent($updatedContent);

  if ($isDraft) {
    $draft = $gdClient->newDraft('yes');
  } else {
    $draft = $gdClient->newDraft('no');
  }

  $control = $gdClient->newControl();
  $control->setDraft($draft);
  $postToUpdate->control = $control;

  $updatedPost = $postToUpdate->save();
  return $updatedPost;
}

Примечание . Изменение данных автора, связанных с сообщениями, в настоящее время не поддерживается.

Удаление сообщений

Чтобы удалить сообщение, передайте URL-адрес редактирования сообщения в метод delete вашего объекта $gdClient , например:

public function deletePost($gdClient, $blogID, $postID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID;
  $gdClient->delete($uri);
}

Комментарии

API данных Blogger позволяет создавать, получать и удалять комментарии. Обновление комментариев не поддерживается (и недоступно в веб-интерфейсе).

Создание комментариев

Чтобы опубликовать комментарий, создайте объект записи и вставьте его следующим образом:

function createComment($gdClient, $blogID, $postID, $commentText)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default';

  $newComment = $gdClient->newEntry();
  $newComment->content = $gdClient->newContent($commentText);
  $newComment->content->setType('text');
  $createdComment = $gdClient->insertEntry($newComment, $uri);

  $editLink = split('/', $createdComment->getEditLink()->href);
  $newCommentID = $editLink[8];

  return $newCommentID; 
}

Примечание . В настоящее время вы можете публиковать комментарии только в блоге, принадлежащем авторизованному пользователю.

Примечание . Установка собственного автора комментариев в настоящее время не поддерживается. Все новые комментарии будут отображаться так, как если бы они были созданы пользователем, прошедшим аутентификацию в данный момент.

Получение комментариев

Вы можете получить комментарии к определенному сообщению из URL-адреса ленты комментариев к этому сообщению:

public function printPostComments($gdClient, $blogID, $postID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default');
  $feed = $gdClient->getFeed($query);
  $printFeed($feed);
}

Или вы можете получить комментарии ко всем публикациям, используя URL-адрес ленты комментариев блога:

http://www.blogger.com/feeds/blogID/comments/default

Удаление комментариев

Чтобы удалить комментарий, передайте URL-адрес редактирования комментария в метод delete вашего объекта $gdClient следующим образом:

public function deleteComment($gdClient, $blogID, $postID, $commentID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default/' . $commentID;
  $gdClient->delete($uri);
}

Вернуться наверх