API Blogger: начало работы

В этом документе объясняется, как начать использовать API Blogger.

Прежде чем начать

Зарегистрируйте аккаунт Google

Убедитесь, что у вас есть учетная запись Google . Мы рекомендуем использовать отдельную учетную запись Google для разработки и тестирования, чтобы защитить себя от случайной потери данных. Если у вас уже есть тестовая учетная запись, то все готово; вы можете перейти в пользовательский интерфейс Blogger , чтобы настроить, отредактировать или просмотреть свои тестовые данные.

Ознакомьтесь с Blogger.

Если вы не знакомы с концепциями Blogger, прочтите этот документ и поэкспериментируйте с пользовательским интерфейсом , прежде чем начинать писать код. Этот документ предполагает, что вы знакомы с Blogger, концепциями веб-программирования и форматами веб-данных.

Узнайте о процедуре авторизации запросов и идентификации вашей заявки.

Когда ваше приложение запрашивает конфиденциальные данные, запрос должен быть авторизован авторизованным пользователем, имеющим доступ к этим данным.

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

Информацию о том, как авторизовать запросы и использовать ключи API, см. в разделе «Авторизация запросов и идентификация вашего приложения» в документе «Использование API».

Фон API Blogger

Концепции блогеров

В основе Blogger лежат пять основных концепций:

  • Блоги : основная концепция API. Блог состоит из постов и страниц. Это контейнер для метаинформации блога, такой как название блога и описание.
  • Записи : Запись в блоге — это опубликованный материал, созданный автором блога. Эта информация должна быть актуальной и отражать то, что автор хочет донести до мира в настоящий момент. Понятно, что со временем контент записей в блоге устаревает и становится менее актуальным.
  • Комментарии : Комментарии — это место, где люди, помимо автора поста в блоге, реагируют на написанное им. Это могут быть самые разные вещи, от кирпичей до букетов.
  • Страницы : Страница — это место для статического контента, такого как биографическая информация или способы связи с пользователем. Как правило, это неизменная информация, которая редко меняется.
  • Пользователи : Пользователь — это тот, кто взаимодействует с Blogger, будь то автор, администратор или просто читатель. В публичных блогах читатели могут быть анонимными, но в частных блогах читатель должен быть идентифицирован Blogger.

Модель данных API Blogger

Ресурс — это отдельная сущность данных с уникальным идентификатором. API Blogger JSON работает с пятью типами ресурсов:

  • Ресурс «Блоги» : обозначает блог.
  • Ресурс «Публикации» : представляет собой публикацию; каждый ресурс «Публикации» является дочерним элементом ресурса «Блоги».
  • Ресурс комментариев : представляет собой комментарий к конкретной публикации; каждый ресурс комментариев является дочерним элементом ресурса публикаций.
  • Ресурс страниц : представляет собой статическую страницу; каждый ресурс страниц является дочерним элементом ресурса блога.
  • Ресурс пользователя : Представляет собой неанонимного пользователя. Используется для идентификации автора страницы, публикации или комментария.
Ресурс «Блоги» имеет два дочерних типа ресурсов: страницы и записи. Ресурс «Записи» может иметь дочерние ресурсы «Комментарии».
Обзор взаимосвязей между ресурсами

Модель данных API Blogger основана на группах ресурсов, называемых коллекциями:

Коллекция блогов
А Коллекция блогов содержит все блоги, к которым пользователь имеет права доступа. Вы можете отсортировать блоги по пользователю или получить доступ к отдельному блогу по его идентификатору.
Коллекция постов
Коллекция «Сообщения» состоит из всех ресурсов сообщений в рамках конкретного ресурса блога .
Сбор комментариев
Коллекция комментариев состоит из всех ресурсов комментариев, содержащихся в конкретном ресурсе публикации .
Коллекция страниц
Коллекция страниц состоит из всех ресурсов страниц в рамках конкретного ресурса блога .
Коллекция пользователей
Коллекция пользователей включает в себя все ресурсы пользователей на Blogger и, следовательно, не может быть представлена ​​в виде списка. Пользователь может получить доступ к своим собственным ресурсам (но ни к чьим другим) по идентификатору или используя идентификатор self .

Операции API Blogger

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

Операция Описание REST HTTP-сопоставления
список Отображает список всех ресурсов в коллекции. GET к URI коллекции.
получать Получает конкретный ресурс. GET по URI ресурса.
getByUrl Получает ресурс, выполняя поиск по URL-адресу. GET с URL-адресом, переданным в качестве параметра.
getByPath Получает ресурс, находя его по пути. GET с указанием пути в качестве параметра.
listByUser Отображает список ресурсов, принадлежащих пользователю. GET из коллекции, принадлежащей пользователю.
поиск Поиск ресурсов на основе параметров запроса. GET к URL-адресу поиска, при этом запрос передается в качестве параметра.
вставлять Создайте ресурс в коллекции. POST на URI коллекции.
удалить Удаляет ресурс. DELETE по URI ресурса.
пластырь Обновите ресурс, используя семантику Patch. PATCH в URI ресурса.
обновлять Обновить ресурс. PUT по URI ресурса.

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

Тип ресурса
Поддерживаемые методы
список получать getByUrl getByPath listByUser поиск вставлять удалить пластырь обновлять
Блоги нет да да нет да нет нет нет нет нет
Сообщения да да нет да нет да да да да да
Комментарии да да нет нет нет нет нет нет нет нет
Страницы да да нет нет нет нет нет нет нет нет
Пользователи нет да нет нет нет нет нет нет нет нет

Стили вызовов

Существует несколько способов вызова API:

ОТДЫХ

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

Термин REST расшифровывается как « Representational State Transfer» (передача репрезентативного состояния ). В контексте API Google это означает использование HTTP-глаголов для получения и изменения представлений данных, хранящихся в Google.

В RESTful-системе ресурсы хранятся в хранилище данных; клиент отправляет запрос серверу на выполнение определенного действия (например, создание, получение, обновление или удаление ресурса), а сервер выполняет действие и отправляет ответ, часто в виде представления указанного ресурса.

В RESTful API от Google клиент указывает действие, используя HTTP-глагол, такой как POST , GET , PUT или DELETE . Он указывает ресурс с помощью глобально уникального URI следующего вида:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Поскольку все ресурсы API имеют уникальные URI, доступные по протоколу HTTP, REST обеспечивает кэширование данных и оптимизирован для работы с распределенной инфраструктурой сети.

Возможно, вам пригодятся определения методов в документации по стандартам HTTP 1.1; они включают спецификации для GET , POST , PUT и DELETE .

REST в API Blogger

Поддерживаемые операции Blogger напрямую соответствуют HTTP-глаголам REST, как описано в разделе «Операции API Blogger» .

Конкретный формат URI для Blogger API следующий:

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

Полное описание используемых URI и результатов для каждой поддерживаемой операции в API приведено в справочном документе по API Blogger .

Примеры

Перечислите блоги, к которым авторизованный пользователь имеет права доступа:

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

Получите доступ к публикациям в блоге code.blogger.com , идентификатор которого — 3213900:

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST из JavaScript

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

В следующем примере выполняется загрузка записи из блога code.blogger.com после замены YOUR-API-KEY на ваш API-ключ.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

Формат данных

JSON

JSON (JavaScript Object Notation) — это распространённый, независимый от языка формат данных, предоставляющий простое текстовое представление произвольных структур данных. Для получения дополнительной информации см. json.org .