はてなブログAPI(はてなブログAtomPub)を使って記事を取得する【PowerShell】

はてなブログAPI(はてなブログAtomPub)とPowerShellを使ってブログの記事を取得するコードの紹介です。

はてなブログAtomPubとは？

はてなブログが提供して下さっているAPIです。

はてなブログの記事(エントリ)・下書きを参照、投稿、編集、削除できるAPIです。

Atom Publishing Protocol(以下 AtomPub) はウェブリソースを公開、編集するためのアプリケーション・プロトコル仕様です。はてなブログのAtomPubと通じて、開発者ははてなブログのエントリを参照、投稿、編集、削除するようなオリジナルのアプリケーションを作成できます。

http://developer.hatena.ne.jp/ja/documents/blog/apis/atomより

このAPIを使えば、はてなブログの記事(エントリ)に対して一通りのCRUD操作を行うことができます。

その中でも、この記事では、記事を参照する機能に焦点を当て、PowerShellでブログの記事を参照する例を紹介します。

はてなブログAPIの使い方

上述の公式ドキュメントには次のように記載されています。

HTTP の GET/POST/PUT/DELETE を特定の URI に対してリクエストし、そのリクエストに規定の XML 文書を加えて送信することでインタフェースが用意している操作を行うことができます。

http://developer.hatena.ne.jp/ja/documents/blog/apis/atomより

HTTPによるリクエストを送信することで、APIをキックすることができます。

HTTPのメソッドを使い分けることで各操作を実行することができます。

また、このAPIでのデータの送受信はXML形式になります。

この後紹介するコードでも、記事の結果を受信しますが、データはXML形式で受信しています。

APIの認証

どんなブログに対してもAPIを使って操作できるわけではありません。

当たり前ですが、APIによる操作を行うためには認証が必要になります。

はてなブログAPIでは次の3種類の認証が使えます。

はてなブログAtomPub を利用するために、クライアントは OAuth 認証、WSSE認証、Basic認証のいずれかを行う必要があります。

http://developer.hatena.ne.jp/ja/documents/blog/apis/atomより

OAuth 認証、WSSE認証、Basic認証の3種類が用意されているわけですが、後述するコードでは実装の簡単さを優先して、Basic認証による認証を使いました。

はてなブログAPIを使うための準備

はてなブログAPIを使うためには、次の3つを確認する必要があります。

• 対象のブログのブログID
• ご自身のはてなID
• ご自身のAPI Key

上記の3つは、はてなブログの管理画面から確認することができます。

管理画面のサイドバーの「設定」をクリックします。

次に詳細設定をクリックします。

下の方にスクロールしていくと、AtomPubという欄があります。

ルートエンドポイントとAPIキーという2つの項目があり、この中に３つの情報があります。

下記の画像を参照下さい。

はてなIDとブログIDはルートエンドポイントの中に、APIキーはそのまま、APIキーです。

コード

PowerShellで実装するに当たり、取り回しを容易にするため、Get-HarenaEntriesという簡単な関数にまとめました。

実装したコードは上述のドキュメントにある、次の仕様の部分です。

コレクション URI を GET することで、ブログエントリ一覧を取得できます。一度に7件のブログエントリを取得できます。また、取得したブログエントリ一覧が、コレクションの部分的リストである場合には、 page パラメータを付与する事で、7件目以降のブログエントリも取得出来ます。続きについては、AtomPub の仕様に基づき、部分的リストの続きは rel=next となる atom:link の href 属性がその URI となります。page パラメータを付与しない場合には、最新の7件を取得します。

上記の説明では1回のリクエストで7つのエントリを返すとありますが、実際返ってくるエントリは10です。

その他、はてなブログAtomPubの詳しい仕様については、はてなブログAtomPub - Hatena Developer Center をご参照下さい。

この記事の趣旨ははてなブログのAPIをPowerShellで使う例の紹介なので、Verboseの表示やエラー処理は省き、スケルトンなコードにしています。

関数の戻り値はSystem.Xml.XmlElementになり、パイプラインで処理するときは、XMLのハンドリングになります。

.EXAMPLEに、よくありそうな使用例を記載しましたので、ご参照頂けますと幸いです。

 

<#
.SYNOPSIS
name:Get-HatenaEntries
return:System.Xml.XmlElement

.DESCRIPTION
はてなブログAPIを使用してblogIdで指定した
ブログの記事一覧を取得することができます。
認証にはベーシック認証を使用します。

.PARAMETER blogId
対象となるブログを特定するために指定するブログIDです。

.PARAMETER apiKey
ベーシック認証で使用するパスワードです。

.PARAMETER hatenaId
ベーシック認証で使用するユーザーIDです。

.EXAMPLE
$blogId='XXX.hatenadiary.com'
$apiKey='aaaaaaaa'
$hatenaId='XXX'

#全ての記事一覧をxmlで取得します。
Get-HatenaEntries -blogId $blogId -apiKey $apiKey -hatenaId $hatenaId

#下書きを除いた記事一覧を取得します。
Get-HatenaEntries -blogId $blogId -apiKey $apiKey -hatenaId $hatenaId|Where-Object{$_.control.draft -eq 'no'}

#記事のタイトルを取得します。
Get-HatenaEntries -blogId $blogId -apiKey $apiKey -hatenaId $hatenaId|Select-Object title

#特定の文字列が存在する記事タイトルを取得します。(例では「text」という文字が含まれる記事を取得します。)
Get-HatenaEntries -blogId $blogId -apiKey $apiKey -hatenaId $hatenaId|Where-Object{$_.content.'#text' -like '*text*'}|Select-Object title

#ブログの形式(マークダウンなど)を、「タイトル:形式」で取得します。
Get-HatenaEntries -blogId $blogId -apiKey $apiKey -hatenaId $hatenaId|ForEach-Object{'{0}:{1}' -f $_.title,$_.content.type}

.NOTES
はてなAPIの詳細は下記の、はてな公式ドキュメントをご参照下さい。
http://developer.hatena.ne.jp/ja/documents/blog/apis/atom

#>
function Get-HatenaEntries{
    param([parameter(mandatory=$true)]$blogId,
      [parameter(mandatory=$true)]$apiKey,
      [parameter(mandatory=$true)]$hatenaId
    )

    $collectionUrl="https://blog.hatena.ne.jp/$($hatenaId)/$($blogId)/atom/entry"
    $pass = ConvertTo-SecureString $apiKey -AsPlainText -Force
    $cr = New-Object System.Management.Automation.PSCredential($hatenaId, $pass)
    $url=$collectionUrl
    do
    {
        $req=Invoke-WebRequest -Method Get -Uri $url -Credential $cr
        $xml=([xml]$req.Content)
        Write-Output $xml.GetElementsByTagName('entry')        
        $url=($xml.feed.link|Where-Object{$_.rel -eq 'next'}).href
    }while ($null -ne $url)
}

使用上の注意

Invoke-WebRequestコマンドレットでBasic認証を行うときは、-Credentialオプションを使用します。

スケルトンなので、apiKeyを平文で渡す単純な実装にしています。

APIキーを他の人に知られてしまうと、最悪ブログを消されてしまうこともあるので、他の人に知られないようにご注意下さい。

終わりに

個人的には、ブログの分析、というと大げさですが、自分の記事について検索窓からは調べられないことを調べるときに使っています。

例えば、マークダウンで書いた記事はどれで、見たままで書いたのはどれで・・・といった調査(結局全部マークダウンで書いてました)や、全然修正していない記事はないか・・・とか。

はてなブログAtomPubの実装の触りのようなコードでしたが、もう少し深入りすれば、PowerShell上から記事の投稿や更新も行うことができます。

記事内文字列の一括置換など、まだ公式ではサポートされていない機能を自作することもできます。

いつになるかわかりませんが、永遠に来ない可能性もありますが、入用になって作成するようなことがあれば、また紹介したいと思います。

というわけで、ここでお読み頂きありがとうございました。

参考

http://developer.hatena.ne.jp/ja/documents/blog/apis/atom