Ten dokument wyjaśnia, jak zacząć korzystać z interfejsu API Bloggera.
Zanim rozpoczniesz
Załóż konto Google
Sprawdź, czy masz skonfigurowane konto Google. Do programowania i testowania zalecamy używanie oddzielnego konta Google, aby chronić się przed przypadkową utratą danych. Jeśli masz już konto testowe, to wszystko. Możesz już korzystać z interfejsu użytkownika Bloggera, by konfigurować, edytować lub wyświetlać dane testowe.
Poznaj Bloggera
Jeśli nie masz wiedzy o Bloggerze, przed rozpoczęciem programowania zapoznaj się z tym dokumentem i eksperymentuj z interfejsem. Zakładamy w nim, że znasz Bloggera, pojęcia związane z programowaniem stron internetowych i formaty danych z sieci.
Dowiedz się więcej o autoryzowaniu żądań i identyfikowaniu aplikacji
Gdy Twoja aplikacja żąda prywatnych danych, musi je autoryzować uwierzytelniony użytkownik, który ma do nich dostęp.
Gdy Twoja aplikacja żąda danych publicznych, nie trzeba autoryzować żądania, ale musi mu towarzyszyć identyfikator, np. klucz interfejsu API.
Informacje o autoryzowaniu żądań i używaniu kluczy interfejsu API znajdziesz w artykule Autoryzacja żądań i identyfikowanie aplikacji w dokumencie „Korzystanie z interfejsu API”.
Tło interfejsu API Bloggera
Pojęcia związane z Bloggerem
Blogger opiera się na pięciu podstawowych koncepcjach:
- Blogi: główna koncepcja interfejsu API. Blog zawiera posty i strony. To jest kontener na metadane bloga, takie jak jego nazwa i opis.
- Posty: post na blogu to możliwy do publikacji element utworzony przez jego autora. Powinny one być aktualne i odzwierciedlać to, co autorzy chcą opublikować obecnie światu. Wiadomo, że z czasem treść postów na blogu rośnie, a jego treść staje się coraz mniej trafna.
- Komentarze: komentarz to miejsce, w którym na to, co piszesz, reagują osoby inne niż autor posta na blogu. Wszystko, od cegieł po bukiety.
- Strony: strona to miejsce, w którym znajdują się treści statyczne, np. informacje biograficzne, lub sposoby kontaktu z użytkownikiem. Są to zwykle informacje ponadczasowe, które nie zmieniają się zbyt często.
- Użytkownicy: użytkownik to osoba korzystająca z Bloggera, np. autor, administrator czy tylko czytelnik. Czytelnicy blogów publicznych mogą być anonimowi, ale w przypadku blogów prywatnych czytelnicy muszą być identyfikowani przez Bloggera.
Model danych interfejsu API Bloggera
Zasób to pojedynczy element danych z unikalnym identyfikatorem. Interfejs API JSON Bloggera działa na 5 rodzajach zasobów:
- Zasób Blogów: reprezentuje bloga.
- Zasób postów: reprezentuje posta, a każdy zasób postów jest elementem podrzędnym zasobu bloga.
- Zasób komentarzy: reprezentuje komentarz do konkretnego posta. Każdy zasób komentarzy jest elementem podrzędnym zasobu postów.
- Zasób Strony: reprezentuje stronę statyczną. Każdy zasób strony jest elementem podrzędnym zasobu bloga.
- Zasób użytkowników: reprezentuje anonimowego użytkownika. Służy do identyfikowania autora strony, posta lub komentarza.
![Zasób blogów zawiera 2 typy zasobów dla dzieci: strony i posty.
Zasób postów może mieć podrzędne zasoby komentarzy.](https://developers-dot-devsite-v2-prod.appspot.com/static/blogger/docs/3.0/blogs-posts-comments.png?authuser=4&hl=pl)
Model danych interfejsu API Bloggera opiera się na grupach zasobów, nazywanych kolekcjami:
- Kolekcja Blogi
- <span="apicollection">Kolekcja blogów składa się ze wszystkich blogów, do których użytkownik ma prawa dostępu. Możesz wyświetlić listę blogów według użytkowników lub pobrać pojedynczy blog według identyfikatora.</span="apicollection">
- Kolekcja postów
- Kolekcja postów składa się ze wszystkich zasobów z postami dostępnych w określonym zasobie na blogach.
- Kolekcja komentarzy
- Kolekcja komentarzy zawiera wszystkie zasoby związane z komentarzami w ramach określonego zasobu z postami.
- Kolekcja Strony
- Kolekcja stron składa się ze wszystkich zasobów stron w konkretnym zasobie na blogu.
- Kolekcja Użytkownicy
- Kolekcja użytkowników składa się ze wszystkich zasobów użytkowników w Bloggerze, więc nie może być wyświetlana na liście. Użytkownik może pobrać własny zasób użytkownika (ale nikogo innego) za pomocą identyfikatora lub identyfikatora
self
.
Operacje interfejsu API Bloggera
W interfejsie Blogger API możesz wywoływać wiele różnych metod dotyczących kolekcji i zasobów, jak opisano w poniższej tabeli.
Operacja | Opis | Mapowania HTTP REST |
---|---|---|
list | Wyświetla listę wszystkich zasobów w kolekcji. | GET w identyfikatorze URI kolekcji. |
pobierz | Pobiera określony zasób. | GET w identyfikatorze URI zasobu. |
getByUrl | Pobiera zasób, wyszukuje go według adresu URL. | GET z adresem URL przekazywanym jako parametr. |
getByPath | Pobiera zasób, wyszukując go według ścieżki. | GET ze ścieżką przekazaną jako parametr. |
listByUser | Wyświetla listę zasobów należących do użytkownika. | GET w kolekcji należącej do użytkownika. |
search | Wyszukiwanie zasobów na podstawie parametru zapytania. | GET w adresie URL wyszukiwania, z zapytaniem przekazywanym jako parametr. |
wstaw | Utwórz zasób w kolekcji. | POST w identyfikatorze URI kolekcji. |
usuń | Usuwa zasób. | DELETE w identyfikatorze URI zasobu. |
poprawka | Aktualizowanie zasobu przy użyciu semantyki poprawki. | PATCH w identyfikatorze URI zasobu. |
zaktualizuj | Aktualizowanie zasobu. | PUT w identyfikatorze URI zasobu. |
W tabeli poniżej znajdziesz metody obsługiwane przez poszczególne typy zasobów. Wszystkie operacje list i get na prywatnych blogach wymagają uwierzytelniania.
Typ zasobu |
Obsługiwane metody |
|||||||||
---|---|---|---|---|---|---|---|---|---|---|
lista | pobierz | getByUrl | getByPath | listByUser | wyszukiwanie | wstaw | usuń | poprawka | zaktualizuj | |
Blogi | nie | tak | tak | nie | tak | nie | nie | nie | nie | nie |
Posty | tak | tak | nie | tak | nie | tak | tak | tak | tak | tak |
komentarzami. | tak | tak | nie | nie | nie | nie | nie | nie | nie | nie |
Strony | tak | tak | nie | nie | nie | nie | nie | nie | nie | nie |
Użytkownicy | nie | tak | nie | nie | nie | nie | nie | nie | nie | nie |
Style połączeń
Interfejs API można wywołać na kilka sposobów:
- Za pomocą REST bezpośrednio lub z JavaScript (nie jest wymagany kod po stronie serwera)
- Za pomocą bibliotek klienta.
REST
REST to styl architektury oprogramowania, który zapewnia wygodne i spójne podejście do żądania i modyfikowania danych.
Skrót REST to reprezentatywny transfer stanowy. W kontekście interfejsów API Google oznacza to używanie czasowników HTTP do pobierania i modyfikowania reprezentacji danych przechowywanych przez Google.
W systemie REST zasoby są przechowywane w magazynie danych. Klient wysyła żądanie, aby serwer wykonał określone działanie (np. utworzenie, pobranie, zaktualizowanie lub usunięcie zasobu), a serwer wykonuje działanie i wysyła odpowiedź, często w formie reprezentacji określonego zasobu.
W interfejsach API typu REST firmy Google klient określa działanie za pomocą czasownika HTTP, takiego jak POST
, GET
, PUT
lub DELETE
. Wskazuje zasób za pomocą globalnie unikalnego identyfikatora URI o następującej postaci:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Ponieważ wszystkie zasoby interfejsu API mają unikalne identyfikatory URI dostępne przez HTTP, interfejs REST umożliwia buforowanie danych i jest zoptymalizowany pod kątem pracy z rozproszoną infrastrukturą sieciową.
Definicje metod znajdziesz w dokumentacji standardów HTTP 1.1. Obejmują one specyfikacje GET
, POST
, PUT
i DELETE
.
REST w interfejsie Blogger API
Obsługiwane operacje Bloggera są mapowane bezpośrednio na czasowniki HTTP REST zgodnie z opisem w sekcji Operacje interfejsu Blogger API.
Identyfikatory URI interfejsu API Bloggera mają następujący format:
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
Pełne wyjaśnienie używanych identyfikatorów URI i wyniki każdej obsługiwanej operacji w interfejsie API znajdziesz w dokumentacji interfejsu Bloggera API.
Przykłady
Lista blogów, do których ma dostęp uwierzytelniony użytkownik:
GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY
Pobierz posty na blogu code.blogger.com o identyfikatorze 3213900:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
REST z JavaScriptu
Interfejs Blogger API możesz wywołać z JavaScriptu, używając parametru zapytania callback
oraz funkcji wywołania zwrotnego.
Gdy przeglądarka wczytuje skrypt, wykonywana jest funkcja wywołania zwrotnego i przesyłana odpowiedź do tej funkcji. Takie podejście umożliwia pisanie zaawansowanych aplikacji, które wyświetlają dane z Bloggera, bez konieczności kodowania po stronie serwera.
Poniższy przykład pozwala pobrać posta z bloga code.blogger.com po zastąpieniu YOUR-API-KEY kluczem interfejsu 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>
Format danych
JSON
JSON (JavaScript Object Notation) to popularny, niezależny od języka format danych, który w prosty sposób przedstawia dowolne struktury danych w formie tekstowej. Więcej informacji znajdziesz na stronie json.org.