V minulém díle jsme si vysvětlili, co je to MetaWeblog API a k čemu je dobré. Umožňuje, aby aplikace mohly manipulovat s obsahem na blogu nebo nějakém pro tyto účely připraveném webu. Hlavním cílem je podpora obrázků a snadného a pohodlného formátování textu. A tyto účely plní MetaWeblog API velice dobře.
MetaWeblog API je rozšířením staršího Blogger API, které umělo pouze základní funkce, nepočítalo se například s uploadem obrázků. MetaWeblog tyto problémy řeší. Celá komunikace funguje na standardu XML-RPC, což je vzdálené volání procedur pomocí XML a HTTP protokolu. Důležité je, aby blog nebo cílový web obsahoval publikační službu, se kterou bude aplikace komunikovat a na které bude volat procedury. O tom, co by tato služba měla umět, se budeme bavi právě v tomto díle. Otázky konkrétní implementace ještě řešit nebudeme, to až v dílech dalších.
Dokumentaci ke standardu najdete na adrese http://www.xmlrpc.com/metaWeblogApi, ovšem daleko přehlednější popsání procedur, které je třeba implementovat, najdete na MSDN na adrese http://msdn2.microsoft.com/en-us/library/bb259697.aspx.
Kominukace mezi aplikací a webovou službou
Jak tedy komunikace mezi aplikací a webovou službou probíhá? Nejprve si zaregistrujeme v aplikaci účet, vyplníme uživatelské jméno a heslo, zadáme adresu publikační služby (důrazně doporučuji pro přístup k této službě používat HTTPS, protože jméno a heslo se posílá v textové podobě, takže není problém, aby si ho kdokoliv přečetl) a volbu potvrdíme. Aplikace zavolá funkci blogger.getUsersBlogs, která vrátí seznam blogů, do kterých uživatel může přispívat. Pokud má uživatel blogů více, aplikace by se měla zeptat, do kterého chce uživatel přispívat. Windows Live Writer po zjištění cílového blogu vytvoří testovací článek a ihned jej pošle na blog, následně si stáhne stránku s tímto článkem, které jde do prohlížeče a zjistí formátování textu, styl a barvu odstavce, barvu pozadí, zkrátka kompletní vzhled stránky. Tato funkcionalita je dosti sporná, protože MetaWeblog API obsahuje i pro zjištění vzhledu blogu vlastní procedury, ty ovšem nikdo nepoužívá. Navíc pokud si na serveru HTML zpracováváte nebo kontrolujete a pozměníte jej, Windows Live Writer je už na stránce nenajde a šablonu nezjistí, použije se standardní vzhled.
Následně si aplikace zavoláním funkce metaWeblog.getCategories vyžádá seznam kategorií. Jeden článek můžete zařadit do libovolného počtu kategorií.
Pak již můžete psát články, můžete do nich vložit obrázky, tabulky, zkrátka co vás napadne. Jakmile je článek hotov, dojde k publikování. Nejprve se zavolá pro každý přiložený obrázek nebo soubor procedura metaWeblog.newMediaObject, které se jako parametr pošle daný soubor a tato procedura vrátí absolutní URL, kde je soubor k dispozici. Aplikace tyto absolutní URL dosadí do výsledného HTML kódu a pak již jen zavolá proceduru metaWeblog.newPost, kam mimo jiné pošle tento HTML kód.
Pokud chcete článek editovat, musí si aplikace nejdříve stáhnout jeho obsah (Windows Live Writer si všechny příspěvky ukládá lokálně k sobě, takže je stahuje pouze v případě, že je nemá). Existují 2 procedury - metaWeblog.getRecentPosts, ta vrátí seznam posledních několika článků, počet článků se předá parametrem, a pak procedura metaWeblog.getPost, které předáte id konkrétního článku a dostanete HTML. Máte ještě k dispozici proceduru blogger.deletePost, která článek smaže.
Článek jednoduše upravíte a aplikace procedurou metaWeblog.editPost pošle upravené HTML a případně před tím pošle znovu soubory a obrázky, které se změnily (mají stejný název jako ty již neaktuální, takže je můžete přepsat).
XML-RPC
Jak jsem již psal dříve, volání těchto procedur funguje na standardu XML-RPC. Webová služba přijme XML data, která obsahují název volané procedury a její parametry, tuto proceduru provede a její návratovou hodnotu pošle zpět také ve formě XML. Podporované datové typy jsou String, Integer, DateTime, Boolean, Base64, Array a Struct. Prvních šest je jasných, Struct je něco jako asociativní pole - seznam hodnot, kde každá má svůj unikátní klíč, pomocí něhož k ní přistupujeme.
Ukázkový požadavek:
<?xml version="1.0"?>
<methodCall>
<methodName>metaWeblog.getPost</methodName>
<params>
<param>
<value>15</value>
</param>
<param>
<value>hell.commiray</value>
</param>
<param>
<value>hell95</value>
</param>
</params>
</methodCall>
Ukázková odpověď:
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>categories</name>
<value>
<array>
<data>
<value>Programování</value>
<value>Grafika</value>
</data>
</array>
</value>
</member>
<member>
<name>dateCreated</name>
<value><dateTime.iso8601>20030729T10:59:48</dateTime.iso8601></value>
</member>
<member>
<name>description</name>
<value>Můj testovací příspěvek.</value>
</member>
<member>
<name>permaLink</name>
<value>http://www.blog.com/post.aspx?id=15</value>
</member>
<member>
<name>postid</name>
<value>15></value>
</member>
<member>
<name>title</name>
<value>Můj testovací příspěvek</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
Je vidět, že struktura požadavků a odpovědí je poměrně složitá, rozhodně chvíli trvá, než se v ní člověk zorientuje.
Pro úplnost přikládám přehled procedur, jejich vstupními parametry a výstupními hodnotami.
| Název procedury |
Vstupní parametry |
Návratová hodnota |
Popis funkce dané procedury |
| blogger. getUsersBlogs |
appkey string
username string
password string |
array (
struct {
url string
blogid string
blogName string
}
) |
Zjistí všechny blogy, ke kterým má uživatel přístup.
url by měla být absolutní adresa blogu, ale vždy se to nedodržuje
blogid je ID blogu a blogName je název blogu.
Přeškrtnuté parametry se ignorují, slouží pouze ke kompatibilitě se staršími službami, nicméně aplikace je posílají. |
| metaWeblog. getCategories |
blogid string
username string
password string |
array (
struct {
title string
description string
}
) |
Zjistí seznam kategorií, které jsou na blogu blogid vytvořeny.
title je název kategorie, který se také bude zasílat v procedurách newPost a editPost jako hodnoty pole
description je popis kategorie, ale doporučuji jej dávat stejný jako název,
protože Word zobrazuje v seznamu kategorií description, ale Live Writer title. |
| metaWeblog. newPost |
blogid string
username string
password string
struct {
title string
description string
dateCreated datetime
categories array
}
publish boolean |
postid string |
Přidá do blogu blogid nový příspěvek a vrátí jeho ID jako postid.
title je název článku, description je HTML článku, categorie je pole názvů ketegorií,
pokud je publish true, článek se ihned zobrazí návštěvníkům, pokud je false, článek není zatím publikován. |
| metaWeblog. editPost |
postid string
username string
password string
struct {
title string
description string
dateCreated datetime
categories array (string)
}
publish boolean |
true |
Upraví příspěvek s ID postid v blogu.
title je název článku, description je HTML článku, categories je pole názvů ketegorií,
pokud je publish true, článek se ihned zobrazí návštěvníkům, pokud je false, článek není zatím publikován. |
| blogger. deletePost |
appkey string
postid string
username string
password string
publish boolean |
true |
Odstraní příspěvek s ID postid z blogu.
Přeškrtnuté parametry se ignorují, slouží pouze ke kompatibilitě se staršími službami, nicméně aplikace je posílají. |
| metaWeblog. getRecentPosts |
blogid string
username string
password string
numberOfPosts integer |
array (
struct {
postid string
title string
description string
dateCreated datetime
permaLink string
publish boolean
categories array (string)
}
) |
Stáhne požadovaný počet (numberOfPosts) posledních příspěvků z blogu blogid.
title je název článku, description je HTML článku, categories je pole názvů kategorií,
publish je true, pokud je článek zobrazen návštěvníkům, permaLink je absolutní URL článku na webu |
| metaWeblog. getPost |
postid string
username string
password string |
struct {
postid string
title string
description string
dateCreated datetime
permaLink string
publish boolean
categories array (string)
} |
Stáhne příspěvek s ID postid.
title je název článku, description je HTML článku, categories je pole názvů kategorií,
publish je true, pokud je článek zobrazen návštěvníkům, permaLink je absolutní URL článku na webu |
| metaWeblog. newMediaObject |
blogid string
username string
password string
struct {
name string
type string
bits base64
} |
struct {
url string
} |
Přidá do blogu blogid soubor přílohy. Vrátí absolutní URL, pod kterou je soubor dostupný.
name je název souboru na klientovi (pokud v daném blogu soubor s takovým názvem existuje, bude přepsán),
type je MIME typ souboru, např. image/png,
bits je binární obsah souboru zapsaný v kódování base64 |
Parametry username a password jsou uživatelské jméno a heslo uživatele, posílají se v nešifrované podobě (někdy čistý text, někdy base64, což ale není šifra a hodnota jde snadno získat), opravdu vřele tedy doporučuji použít SSL pro přístup k publikační službě. U parametrů záleží na pořadí, pokud je ale parametr ve struktuře, na pořadí nezáleží, protože se spolu s hodnotou předává i název parametru. U parametrů, které ve struktuře nejsou, se název parametru nepředává.
To je protentokrát vše, v příštím díle si ukážeme, jak takovou službu implementovat a poukážeme na některá úskalí, se kterými se můžeme potkat.