API данных Blogger позволяет клиентским приложениям просматривать и обновлять контент Blogger в виде фидов API данных Google.
Ваше клиентское приложение может использовать API данных Blogger для создания новых сообщений в блогах, редактирования или удаления существующих сообщений в блогах и запроса сообщений в блогах, соответствующих определенным критериям.
В дополнение к некоторым сведениям о возможностях API данных Blogger в этом документе приводятся примеры базовых взаимодействий API данных с использованием необработанного XML и HTTPS. После прочтения этого документа вы можете узнать больше о взаимодействии с API с помощью наших клиентских библиотек , прочитав разделы этого руководства для разработчиков, посвященные конкретным языкам программирования.
Содержание
Аудитория
Этот документ предназначен для программистов, которые хотят писать клиентские приложения, способные взаимодействовать с Blogger с помощью XML и HTTPS.
В этом документе предполагается, что вы понимаете общие идеи протокола API данных Google .
Если вы используете систему UNIX и хотите попробовать примеры из этого документа без написания кода, вам могут пригодиться утилиты командной строки UNIX curl
или wget
; для получения дополнительной информации см. справочные страницы для этих утилит.
Справочную информацию об API данных Blogger см. в справочном руководстве по протоколу .
Начиная
Создание учетной записи блогера
Вы можете зарегистрировать учетную запись Blogger в целях тестирования. Blogger использует учетные записи Google , поэтому, если у вас уже есть учетная запись Google, все готово.
Авторизация запросов
Когда ваше приложение запрашивает закрытые пользовательские данные, оно должно включать токен авторизации. Токен также идентифицирует ваше приложение для Google.
О протоколах авторизации
Мы рекомендуем использовать OAuth 2.0 для авторизации запросов.
Blogger GData API также поддерживает более старые варианты авторизации, такие как OAuth 1.0 , AuthSub или ClientLogin ; однако в большинстве случаев мы не рекомендуем использовать другие варианты. Если ваше приложение уже использует эти параметры, мы рекомендуем по возможности перейти на OAuth 2.0.
Если ваше приложение имеет определенные необычные требования к авторизации, такие как вход в систему одновременно с запросом доступа к данным ( гибридный ) или делегирование полномочий на уровне домена ( 2LO ), то в настоящее время вы не можете использовать токены OAuth 2.0. В таких случаях вы должны вместо этого использовать токены OAuth 1.0.
Авторизация запросов с помощью OAuth 2.0
Запросы к Blogger GData API для непубличных пользовательских данных должны быть авторизованы пользователем, прошедшим проверку подлинности.
Детали процесса авторизации или «потока» для OAuth 2.0 несколько различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применяется ко всем типам приложений:
- Когда вы создаете свое приложение, вы регистрируете его в Google . Затем Google предоставляет информацию, которая понадобится вам позже, например идентификатор клиента и секрет клиента.
- Когда вашему приложению требуется доступ к пользовательским данным, оно запрашивает у Google определенную область доступа.
- Google отображает диалоговое окно OAuth для пользователя, предлагая ему разрешить вашему приложению запрашивать некоторые из его данных.
- Если пользователь одобряет, Google предоставляет вашему приложению краткосрочный токен доступа .
- Ваше приложение запрашивает данные пользователя, прикрепляя к запросу токен доступа.
- Если Google определяет, что ваш запрос и токен действительны, он возвращает запрошенные данные.
Некоторые потоки включают дополнительные шаги, например использование маркеров обновления для получения новых маркеров доступа. Подробную информацию о потоках для различных типов приложений см. в документации Google по OAuth 2.0 .
Вот информация об области действия OAuth 2.0 для Blogger GData API:
https://www.blogger.com/feeds/
Чтобы запросить доступ с помощью OAuth 2.0, вашему приложению требуется информация о области, а также информация, которую Google предоставляет во время регистрации приложения (например, идентификатор клиента и/или секрет клиента).
Совет . Клиентские библиотеки API Google могут выполнить часть процесса авторизации за вас. Они доступны для различных языков программирования; проверьте страницу «Библиотеки и примеры» для получения более подробной информации.
Указание версии
В каждом запросе, который вы отправляете с помощью API данных Blogger, должна быть указана версия 2 API.
Чтобы указать номер версии, используйте HTTP-заголовок GData-Version
:
GData-Version: 2
В качестве альтернативы, если вы не можете установить заголовки HTTP, вы можете указать v=2
в качестве параметра запроса в URL-адресе. Но HTTP-заголовок предпочтительнее, где это возможно.
Примечание . Клиентские библиотеки автоматически предоставляют соответствующие заголовки версий, поэтому не используйте параметр запроса v=2
при использовании клиентской библиотеки.
Получение списка блогов
API данных Blogger предоставляет фид, в котором перечислены блоги определенного пользователя; этот канал известен как «метаканал».
Отправьте запрос HTTP GET
на следующий URL-адрес, чтобы получить список блогов:
https://www.blogger.com/feeds/profileID/blogs
Где идентификатор профиля — это число в URL-адресе страницы профиля пользователя.
Примечание . Вы также можете заменить идентификатор пользователя по default
, чтобы Blogger возвращал список блогов для пользователя, учетные данные которого прилагаются к запросу.
Запись в метафиде может выглядеть так:
<entry gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'> <id>tag:blogger.com,1999:user-userNumber.blog-blogID</id> <published>2006-08-02T18:44:43.089-07:00</published> <updated>2008-04-17T00:03:33.152-07:00</updated> <title>Lizzy's Diary</title> <summary type='html'>Being the journal of Elizabeth Bennet</summary> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/profileID/blogs/blogID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/' /> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default' /> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default' /> ... <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> </entry>
Информацию о том, что означает каждый из этих элементов, см. в документе Справочник по протоколу API данных Google или в спецификации Atom 1.0 .
Если по какой-либо причине ваш запрос не будет выполнен, Blogger может вернуть другой код состояния. Дополнительные сведения о кодах состояния HTTP также доступны в документе Справочник по протоколу API данных Google .
Создание постов
API данных Blogger позволяет создавать и публиковать новые записи в блогах, а также создавать черновики записей.
Публикация сообщения в блоге
После аутентификации вы можете публиковать новые записи в блоге.
Сначала создайте XML-представление публикации для публикации. Этот XML должен быть в форме элемента <entry>
Atom, который может выглядеть следующим образом:
<entry xmlns='http://www.w3.org/2005/Atom'> <title type='text'>Marriage!</title> <content type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml"> <p>Mr. Darcy has <em>proposed marriage</em> to me!</p> <p>He is the last man on earth I would ever desire to marry.</p> <p>Whatever shall I do?</p> </div> </content> <category scheme="http://www.blogger.com/atom/ns#" term="marriage" /> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" /> </entry>
Примечание . Установка собственного автора для сообщений в настоящее время не поддерживается. Все новые сообщения будут отображаться так, как если бы они были созданы текущим аутентифицированным пользователем.
Чтобы опубликовать эту запись, отправьте ее по URL-адресу сообщения в блоге следующим образом. Сначала поместите элемент <entry>
Atom в тело нового запроса POST
, используя тип содержимого application/atom+xml
. Затем найдите URL сообщения блога в метаканале, найдя элемент <link>
, где атрибут rel
заканчивается на #post
. URL-адрес сообщения блога задается как атрибут href
этого элемента, который имеет следующий формат:
https://www.blogger.com/feeds/blogID/posts/default
Примечание . Этот URL-адрес совпадает с URL-адресом в <link rel="service.post">
, который появляется в разделе <head>
удобочитаемой версии блога.
Blogger создает сообщение в блоге, используя отправленную вами запись, а затем возвращает код состояния HTTP 201 CREATED
вместе с копией нового сообщения в виде элемента <entry>
. Возвращается та же запись, которую вы отправили, но она также содержит различные элементы, добавленные Blogger, например элемент <id>
.
Если по какой-либо причине ваш запрос не будет выполнен, Blogger может вернуть другой код состояния. Информацию о кодах состояния см. в справочном документе по протоколу API данных Google .
Создание черновика сообщения в блоге
Черновики сообщений создаются так же, как общедоступные сообщения, но с добавлением к записи элемента <app:control>
, указывающего, что сообщение не должно (пока) публиковаться.
Этот элемент <app:control>
должен содержать один дочерний элемент <app:draft>
:
<app:control xmlns:app='http://www.w3.org/2007/app'> <app:draft>yes</app:draft> </app:control>
Данные, содержащиеся в элементе <app:draft>
, должны быть строкой yes , чтобы сообщение было распознано как черновик.
Вы можете превратить существующий черновик сообщения в блоге в опубликованное сообщение, получив черновик сообщения, задав для данных элемента <app:draft>
строку no , а затем обновив сообщение. Получение и обновление сообщений рассматривается в следующих двух разделах.
Примечание . Дополнительные сведения о протоколе публикации Atom, включая пространства имен <app:control>
и <app:draft>
, см. в RFC 5023 .
Получение сообщений
В следующих разделах описано, как получить список сообщений блога с параметрами запроса и без них.
Вы можете запросить общедоступную ленту Blogger без аутентификации. Таким образом, вам не нужно задавать параметр Authorization при получении сообщений из общедоступного блога.
Получение всех сообщений в блоге
Чтобы получить сообщения пользователя, отправьте HTTP- GET
на URL-адрес фида блога. Затем Blogger возвращает фид, содержащий соответствующие записи блога. Например, чтобы получить список сообщений блога для liz@gmail.com, отправьте в Blogger следующий HTTP-запрос (конечно, с соответствующим значением вместо blogID
):
GET https://www.blogger.com/feeds/blogID/posts/default
Затем Blogger возвращает код состояния HTTP 200 OK
и стандартную ленту Atom 1.0, содержащую записи блога.
Ниже приведен пример ленты для блога с одним сообщением. Обратите внимание, что мы немного отредактировали этот пример, чтобы сделать его более понятным для людей. В частности, реальный канал Blogger содержит фактические идентификаторы и URL-адреса.
<?xml version='1.0' encoding='utf-8'?> <?xml-stylesheet href="http://www.blogger.com/styles/atom.css" type="text/css"?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"D08FQn8-eip7ImA9WxZbFEw."'> <id>tag:blogger.com,1999:blog-blogID</id> <updated>2008-04-17T00:03:33.152-07:00</updated> <title>Lizzy's Diary</title> <subtitle type='html'></subtitle> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> <generator version='7.00' uri='http://www2.blogger.com'>Blogger</generator> <entry gd:etag='W/"D0YHRn84eip7ImA9WxZUFk8."'> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2008-04-07T20:25:00.005-07:00</published> <updated>2008-04-07T20:25:37.132-07:00</updated> <title>Quite disagreeable</title> <content type='html'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></content> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2008/04/quite-disagreeable.html' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> </entry> </feed>
Повторное получение сообщения в блоге
Если вы хотите получить ранее полученную публикацию, вы можете повысить эффективность, указав Blogger отправлять публикацию только в том случае, если она изменилась с момента последней загрузки.
Чтобы выполнить такого рода условный поиск, отправьте HTTP- GET
, который включает HTTP-заголовок If-None-Match
. В заголовке укажите ETag записи, который можно найти в атрибуте gd:etag
элемента <entry>
.
Например:
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
Когда Blogger получает этот запрос, он проверяет, имеет ли запрошенная вами запись тот же ETag, что и указанный вами ETag. Если ETag совпадают, запись не изменилась, и Blogger возвращает код состояния HTTP 304 Not Modified
.
Если ETag не совпадают, значит, запись была изменена с момента последнего запроса, и Blogger возвращает запись.
Дополнительную информацию о ETags см. в справочном руководстве по API данных Google .
Получение сообщений с использованием параметров запроса
API данных Blogger позволяет запрашивать набор записей, соответствующих заданным критериям, например, запрашивать сообщения в блоге, опубликованные или обновленные в указанном диапазоне дат.
Например, чтобы отправить запрос диапазона дат, добавьте в URL-адрес запроса параметры publish published-min
и published-max
. Чтобы получить все записи блога, созданные в период с 16 марта 2008 г. по 24 марта 2008 г., отправьте HTTP-запрос на URL-адрес фида блога:
GET https://www.blogger.com/feeds/blogID/posts/default?published-min=2008-03-16T00:00:00&published-max=2008-03-24T23:59:59
Когда вы отправляете этот GET
, Blogger возвращает код состояния HTTP 200 OK
и фид, содержащий все записи блога, созданные в указанный вами диапазон дат.
Параметры updated-min
и updated-max
также могут использоваться для обновления всех записей блога в заданном диапазоне. Однако обратите внимание, что эти параметры игнорируются, если для параметра orderby
также не задано значение updated
.
API данных Blogger поддерживает следующие параметры запроса:
- альтернативный
- Тип возвращаемого фида, например,
atom
(по умолчанию) илиrss
. - /category
- Задает категории (также известные как метки) для фильтрации результатов веб-канала. Например,
https://www.blogger.com/feeds/ blogID /posts/default/-/Fritz/Laurie
возвращает записи с ярлыкамиFritz
иLaurie
. - максимальные результаты
- Максимальное количество возвращаемых записей.
- Сортировать по
- Порядок, в котором возвращаются записи, такие как
lastmodified
(по умолчанию),starttime
илиupdated
. - опубликовано-мин., опубликовано-макс.
- Границы дат публикации записей.
- начальный индекс
- Отсчитываемый от 1 индекс первого извлекаемого результата (для разбиения по страницам).
- обновлено-минимум, обновлено-макс.
- Границы дат обновления записей. Эти параметры запроса игнорируются, если для параметра
orderby
не задано значениеupdated
. - дорожка
- Путь постоянной ссылки для сообщения. Например, для публикации с URL-адресом http://buzz.blogger.com/2011/08/bloggers-fresh-new-look.html путь постоянной ссылки будет
/2011/08/bloggers-fresh-new-look.html
./2011/08/bloggers-fresh-new-look.html
. - д
- Полнотекстовая строка запроса. Это позволяет вам искать в блоге сообщения, соответствующие запросу.
Дополнительные сведения о параметрах запроса см. в Справочном руководстве по API данных Blogger и Справочном руководстве по API данных Google .
Обновление сообщений
Чтобы обновить существующую запись в блоге, сначала вы извлекаете запись, которую хотите обновить, затем изменяете ее, а затем отправляете запрос PUT
с обновленной записью в теле сообщения на URL-адрес редактирования публикации. Убедитесь, что значение <id>
в записи, которую вы PUT
, точно соответствует <id>
существующей записи.
URL-адрес редактирования выделен в следующей записи:
<entry gd:etag='W/"CUYDSXo8fSp7ImA9WB9UFkU."'> <id>tag:blogger.com,1999:blog-blogID.post-postID</id> <published>2006-11-08T18:10:00.000-08:00</published> <updated>2006-11-08T18:10:14.954-08:00</updated> <title type='text'>Quite disagreeable</title> <content type='html'><p>I met Mr. Bingley's friend Mr. Darcy this evening. I found him quite disagreeable.</p></content> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2006/11/quite-disagreeable.html'> </link> <link rel='self' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/posts/default/postID'> </link> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/posts/default/postID'> </link> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Bingley" /> <category scheme="http://www.blogger.com/atom/ns#" term="Mr. Darcy" /> <author> <name>Elizabeth Bennet</name> <email>noreply@blogger.com</email> <uri>http://www.blogger.com/profile/profileID</uri> </author> </entry>
ВАЖНО . Чтобы обеспечить совместимость с последующими версиями, убедитесь, что при PUT
обновленной записи сохраняется весь XML-код, который присутствовал при извлечении записи из Blogger. В противном случае, когда мы реализуем новые вещи и включаем элементы <new-awesome-feature>
в ленту, ваш клиент не вернет их, а ваши пользователи пропустят. Все клиентские библиотеки Google Data API обрабатывают это правильно, поэтому, если вы используете одну из библиотек, все готово.
Примечание . Изменение данных об авторе, связанных с сообщениями, в настоящее время не поддерживается.
Совет по устранению неполадок . Некоторые брандмауэры блокируют сообщения HTTP PUT
. Чтобы обойти это, вы можете включить заголовок X-HTTP-Method-Override: PUT
в запрос POST
. Подробнее см. в документе с основами протокола Google Data API .
Удаление сообщений
Чтобы удалить сообщение, отправьте запрос DELETE
на URL-адрес редактирования сообщения. Это тот же URL, который используется для обновления сообщений .
Совет по устранению неполадок . Некоторые брандмауэры блокируют сообщения HTTP DELETE
. Чтобы обойти это, вы можете включить заголовок X-HTTP-Method-Override: DELETE
в запрос POST
. Подробнее см. в документе с основами протокола Google Data API .
Комментарии
API данных Blogger позволяет создавать, извлекать и удалять комментарии. Обновление комментариев не поддерживается (и недоступно в веб-интерфейсе).
Создание комментариев
Чтобы опубликовать комментарий, создайте элемент <entry>
Atom, как показано ниже:
<entry xmlns='http://www.w3.org/2005/Atom'> <title type="text">This is my first comment</title> <content type="html">This is my first comment</content> </entry>
Чтобы опубликовать этот комментарий, поместите элемент <entry>
Atom в тело нового запроса POST
, используя тип содержимого application/atom+xml
. Затем отправьте запрос POST
на соответствующий URL-адрес Blogger:
POST https://www.blogger.com/feeds/blogID/postID/comments/default
Примечание . В настоящее время вы можете публиковать комментарии только в блоге, принадлежащем авторизованному пользователю.
Примечание . В настоящее время установка собственного автора для комментариев не поддерживается. Все новые комментарии будут отображаться так, как если бы они были созданы пользователем, прошедшим проверку подлинности в данный момент.
Получение комментариев
Вы можете получить комментарии для определенного сообщения, отправив GET
на URL-адрес канала комментариев этого сообщения:
GET https://www.blogger.com/feeds/blogID/postID/comments/default
Или вы можете получить комментарии ко всем сообщениям, используя URL-адрес фида комментариев блога:
GET https://www.blogger.com/feeds/blogID/comments/default
Эти запросы возвращают ленту комментариев, которая выглядит следующим образом:
<?xml version='1.0' encoding='utf-8'?> <?xml-stylesheet href="http://www.blogger.com/styles/atom.css" type="text/css"?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"CUYMQ348fyp7ImA9WB9UFkU."'> <id>tag:blogger.com,1999:blog-blogID.postpostID..comments</id> <updated>2007-12-14T17:46:22.077-08:00</updated> <title>Comments on Lizzy's Diary: Quite disagreeable</title> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://blogName.blogspot.com/feeds/postID/comments/default' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/postID/comments/default' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>noreply@blogger.com</email> </author> <generator version='7.00' uri='http://www.blogger.com'>Blogger</generator> <openSearch:totalResults>1</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <entry gd:etag='W/"CUYCQX47eSp7ImA9WB9UFkU."'> <id>tag:blogger.com,1999:blog-blogID.post-commentID</id> <published>2007-12-14T17:46:00.001-08:00</published> <updated>2007-12-14T17:46:00.001-08:00</updated> <title>Darcy FTW!</title> <content type='html'>Darcy FTW!</content> <link rel='edit' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' /> <link rel='self' type='application/atom+xml' href='http://www.blogger.com/feeds/blogID/postID/comments/default/commentID' /> <link rel='alternate' type='text/html' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html?showComment=1197683160001#ccommentID' title='' /> <author> <name>Elizabeth Bennet</name> <uri>http://www.blogger.com/profile/profileID</uri> <email>liz@gmail.com</email> </author> <thr:in-reply-to xmlns:thr='http://purl.org/syndication/thread/1.0' href='http://blogName.blogspot.com/2007/12/quite-disagreeable_5283.html' ref='tag:blogger.com,1999:blog-blogID.post-postID' source='http://www.blogger.com/feeds/blogID/posts/default/postID' type='text/html' /> </entry> </feed>
Удаление комментариев
Чтобы удалить комментарий, отправьте запрос DELETE
на URL редактирования комментария. Этот URL выделен в ленте комментариев выше.
Формат экспорта
Blogger позволяет пользователям экспортировать и импортировать свои блоги с помощью файла экспорта Blogger. Этот экспортный файл содержит все сообщения и комментарии для одного блога. Формат файла экспорта — это точно такой же формат Atom, который описан в разделах, посвященных получению сообщений и комментариев. Этот экспортный файл будет содержать содержимое ленты сообщений и содержимое ленты комментариев, объединенных в один документ.
Чтобы экспортировать или импортировать данные блога с использованием формата экспорта, вы можете посетить страницу настроек блога. Чтобы получить файл экспорта для блога с помощью Data API, используйте следующий URL-адрес:
GET https://www.blogger.com/feeds/blogID/archive
Чтобы импортировать файл экспорта, создайте запрос POST
по следующему URL-адресу с содержимым файла экспорта в качестве данных запроса и application/atom+xml
в качестве типа содержимого:
POST https://www.blogger.com/feeds/blogID/archive/full
Ни один из приведенных выше URL-адресов не поддерживает параметры запроса. Оба запроса также должны содержать информацию для аутентификации , и только администраторы блога смогут импортировать/экспортировать блог, используя эти URL-адреса каналов.
Примечание . Если вы создаете собственный экспортный файл Blogger, в настоящее время существует одно ограничение, касающееся порядка записей сообщений и комментариев. В файле экспорта Blogger сначала будут перечислены все сообщения, а затем все комментарии. Чередование постов и комментариев разрешено, если комментарий идет после поста, для которого он предназначен.
Дополнительные сведения о том, как Blogger использует формат Atom в файле экспорта, см. в справочном руководстве по протоколу .