TopMovable TypeDataAPI > 2013年8月
2013年8月22日

Movable Type Data APIの使い方:paramsについて

August 22,2013 12:55 AM
Tag:[, ]
Permalink

Movable Type 6から提供されるData APIの使い方を紹介します。

本エントリーでは、JavaScript SDK APIのparamsの使い方について解説します。

1.APIのparamsについて

Data APIのドキュメントでは数多くのAPIに「params」が設定できるように書かれています。

Data APIのドキュメント「listEntries()」より抜粋
listEntries

paramsはAPIを実行するときのオプションで、たとえば取得するオブジェクトの件数や返却時のフィールドを指定することができます。

ということで以下、listEntries()を使ってparamsの設定方法をいくつか紹介します。

サンプルではJavaScriptライブラリのインクルードやapiの生成・エラーのハンドリング等を省略しているので、以下の記事を参照して適宜追加してください。

jQueryを利用しているので、jQueryのインクルードも行ってください。

2.取得記事をフィルタリングする

Movable Type Data APIの使い方:listEntries()」で記事一覧を取得する基本的な使い方を解説しましたが、このままではすべての記事を取得してしまいます(厳密にはAPI側で50記事に絞られるようです)。

listEntries()では、paramsを第2パラメータに設定することで、取得する記事をフィルタリングすることができます。

たとえば新着3件の記事を表示するには、「limit:」を設定した変数paramsをlistEntries()に設定します。

<script>
// API生成コード等は省略
 
var siteId = 2;
var params = {
  limit: 3
};
api.listEntries(siteId, param, function(response) {
  if (response.error) {
    return;
  }
  for (i=0; i< response.items.length; i++) {
    jQuery('#result').append($('<li>').append(response.items[i].title));
  }
});
</script>
<div id="result"></div>

赤字が「Movable Type Data APIの使い方:listEntries()」のサンプルコードに追加した部分になります。

その他、以下のパラメータが設定できるようです(listEntries()では使われないと思われるパラメータも含まれています)。

  • sortBy:'title'や'authored_on'などを指定
  • sortOrder:'ascned'または'descend'を指定
  • limit:記事件数を指定
  • offset:除外したい記事数を指定
  • scope:'blog'または'website'または'system'
  • blog_id:ブログID
  • blog_ids:複数のブログID

他にも設定可能なパラメータがあるようですが、動作未確認なのでここでは割愛しています。

3.取得記事のフィールドを特定する

2項のコードでは、返却されるJSONデータにすべてのフィールドが設定されてしまい、パフォーマンス上好ましくありませんん。

たとえばJSONデータを記事タイトルとパーマリンクだけに特定したい場合は、パラメータに「field:」を設定します。

<script>
// API生成コード等は省略
 
var siteId = 2;
var params = {
  limit: 3,
  fields: 'title, permalink'
};
api.listEntries(siteId, param, function(response) {
  if (response.error) {
    return;
  }
  for (i=0; i< response.items.length; i++) {
    jQuery('#result').append($('<li>').append(response.items[i].title));
  }
});
</script>
<div id="result"></div>

「field:」の値に、取得したいフィールドを設定します。複数取得する場合はカンマ区切りで設定します。

設定可能なフィールドは収集するオブジェクトによって異なります。

4.指定した文字列でフィルタリングする

パラメータに「search:」を加え、値に文字列を設定することで、文字列を含む記事だけにフィルタリング、つまり検索することができます。

<script>
// API生成コード等は省略
 
var siteId = 2;
var params = {
  limit: 3,
  fields: 'title, permalink',
  search: 'hoge',
  searchFields: 'title, body'
};
api.listEntries(siteId, param, function(response) {
  if (response.error) {
    return;
  }
  for (i=0; i< response.items.length; i++) {
    jQuery('#result').append($('<li>').append(response.items[i].title));
  }
});
</script>
<div id="result"></div>

「searchFields:」は検索対象のフィールドを指定します。「searchFields:」は必須ではないようです。

Comments [0] | Trackbacks [0]
2013年8月20日

Movable Type Data APIの使い方:listEntries()

August 20,2013 12:03 AM
Tag:[, ]
Permalink

Movable Type 6から提供されるData APIの使い方を紹介します。

本エントリーではJavaScript SDK APIのlistEntries()の基本的な使い方について解説します。

1.基本

listEntries()はパラメータに設定した条件にしたがって記事一覧を収集するためのAPIです。

listEntries()を使って記事一覧を表示する簡単なサンプルを紹介します。

<script>
// API生成コード等は省略
 
var siteId = 2;
api.listEntries(siteId, function(response) {
  if (response.error) {
    return;
  }
  for (i=0; i< response.items.length; i++) {
    jQuery('#result').append($('<li>').append(response.items[i].title));
  }
});
</script>
<div id="result"></div>

JavaScriptライブラリのインクルードやapiの生成については「Movable Type Data APIの使い方(JavaScript SDKを使ったオブジェクトの生成)」を参照してください。

また、エラーのハンドリングについては「Movable Type Data APIの使い方(エラーのハンドリング)」を参照してください。

なお、上記のサンプルでは結果表示処理でjQueryを利用しているので、jQueryのインクルードも行ってください。

2.パラメータ

listEntriesに設定するパラメータは次のとおりです。

  • siteId:ブログIDを設定(必須)
  • コールバック:レスポンス受信時の処理を記述

このエントリーでは省略していますが、第2パラメータとしてオプションを設定することも可能です。詳細は別のエントリーで紹介します。

3.レスポンス

レスポンスとして次のようなJSONデータが返却されます(MT6ベータ版時点でのサンプル)。

{
    "totalResults": 3,
    "items": [{
        "excerpt": "テスト投稿です。...",
        "date": "2013-07-10T23:08:07+09:00",
        "status": "Publish",
        "updatable": false,
        "author": {
            "userpicUrl": null,
            "displayName": "hoge"
        },
        "comments": [],
        "allowComments": true,
        "permalink": "http://user-domain/test.html",
        "keywords": "",
        "body": "テスト投稿です。",
        "trackbacks": [],
        "id": 1,
        "allowTrackbacks": true,
        "modifiedDate": "2013-08-07T22:05:26+09:00",
        "trackbackCount": "0",
        "blog": {
            "id": "2"
        },
        "categories": [],
        "tags": [],
        "commentCount": "0",
        "assets": [],
        "basename": "test",
        "createdDate": "2013-07-10T23:08:20+09:00",
        "class": "entry",
        "title": "テスト",
        "pingsSentUrl": [],
        "more": "",
        "customFields": [{
            "basename": "cftext",
            "value": "aaa"
        }]
    }, {
        …2件目(略)…
    }, {
        …3件目(略)…
    }]
}

データの意味は次のとおりです。

totalResults
記事数を保持します(ベータ1では公開状態の全記事件数)。

items
記事データオブジェクトを配列で保持します。

itemsの中から主に次のデータが収集可能です。

  • blog:ブログID
  • class:記事クラス
  • id:記事ID
  • title:記事タイトル
  • body:記事本文
  • more:記事追記
  • excerpt:記事概要
  • date:公開日時
  • createdDate:作成日時
  • modifiedDate:更新日時
  • status:公開状態
  • author:記事作成ユーザー
  • comments:コメント
  • permalink:記事のパーマリンク
  • keywords:キーワード
  • categories:カテゴリ
  • tags:タグ
  • basename:ベースネーム
  • customFields:カスタムフィールド

4.レスポンスデータから記事データを取得する

レスポンスデータから記事データを順次取得するには次のようにします。

api.listEntries(siteId, function(response) {
  for (i=0; i&lt; response.items.length; i++) {
    alert(response.items[i].title);
  }
});

for文で配列itemsの要素数分繰り返し処理を行い、for文の中でコールバックの引数responseからデータを抜き出します。

ハッシュ・配列はピリオド、さらに配列は[]で要素を指定します。

たとえば1番目の記事データから記事タイトルを取得する場合は、

response.items[1].title

となります。

2番目の記事データからブログIDを取得するには、

response.items[2].blog.id

とします。

3番目の記事データからカスタムフィールド0番目の値を取得するには、

response.items[3].customFields[0].value

とします。

カスタムフィールドについては、配列customFieldsの何番目に何のカスタムフィールドが設定されているか、ベースネームから判定する必要があります。

response.items[3].customFields[0].basename
Comments [0] | Trackbacks [0]
2013年8月 7日

Movable Type Data APIの使い方(エラーのハンドリング)

August 7,2013 12:55 AM
Tag:[, , ]
Permalink

Movable Type Data APIの使い方について紹介します。

本エントリーでは、JavaScript SDKを使った場合のエラーのハンドリング方法について解説します。

1.エラーデータの構成

DataAPIを実行して、たとえば「指定したサイトが見つかりません」というエラーになった場合のjsonデータは次のようになります。

{
    "error": 
    {
        "message": "Site not found",
        "code": 404
    }
}

データの意味は次の通りです(多分)。

  • code:HTTPのエラーコード
  • message:エラー理由

2.エラーのハンドリング

JavaScript SDKを使った場合、次のように「response.error」で判定し、詳細なメッセージについては「response.error.message」や「response.error.code」として出力するとよいでしょう。

api.listEntries(20, function(response) {
    if (response.error) {
        alert(response.error.code + ":" + response.error.message);
        return;
    }
    // OKのときの処理を記述
});

どのAPIでもエラー発生時のjsonデータの構造は同じになると思われますので、エラーのハンドリングについても、APIによって処理を変更したい場合を除き、同じ実装を行えばよいでしょう。

Comments [0] | Trackbacks [0]
2013年8月 5日

Movable Type Data APIの使い方(JavaScript SDKを使ったオブジェクトの生成)

August 5,2013 12:03 AM
Tag:[, ]
Permalink

Movable Type 6から提供されるData APIの使い方を紹介します。

本エントリーではJavaScript SDKを使ったオブジェクトの作り方について解説します。

1.jQueryとmt-data-api.js

Data APIを利用するためには、script要素でjQueryとJavaScript SDKに含まれる「mt-data-api.min.js」または「mt-data-api.js」を引き込みます。

<script src="http://user-domain/mt-static/data-api/v1/js/mt-data-api.min.js"></script>

「mt-data-api.min.js」または「mt-data-api.js」はMT6であれば、「/mt-static/data-api/v1/js」配下に置かれているのでこれを利用します。

2.コンストラクタ

Data APIのオブジェクト生成(コンストラクタ)は、次のように「MT.DataAPI」を利用します。

<script>
var api = new MT.DataAPI({
    clientId: 'foo',
    baseUrl:  'http://user-domain/mt-data-api.cgi',
});
</script>

clientID
クライアントIDを設定します。設定可能な値はアルファベットと数字、アンダースコアとハイフンです。clientIDはMTログインユーザ名でなく、任意の文字列で構いません。このIDは認証やcookieを利用する場合に利用されるようです。このオプションは必須です。

baseUrl
DataAPI用CGIのURLを記述します。MT6であればアプリケーションディレクトリ(MTのインストールディレクトリ)直下にあります。このオプションは必須です。

format
返却値のフォーマットを指定します。デフォルトは「json」です。

async
非同期でAPIを動作させたくない場合に「false」を設定します。デフォルトは「true」です。

上記のオプションを指定した場合のサンプルは次のとおりです。

var api = new MT.DataAPI({
    clientId: 'foo',
    baseUrl: 'http://user-domain/mt-data-api.cgi',
    format: 'json',
    async: true,
});

その他にもセッションやキャッシュを利用する場合のオプションが用意されています。詳細は以下のページをご覧ください。

DataAPI SDK english MT.DataAPI Constructor

2013.08.05
オブジェクト生成でjQueryは必要ないので削除しました。

Comments [0] | Trackbacks [0]
Now loading...
ギターに入った猫
掲載広告募集
Styles
Font Size
Default
For defective color vision
Gray Scale
RGB Color
Search this site

このブログをメールで購読する by:FeedBurner

AMN
Categories
Monthly Archives
2020年
2019年
2018年
2017年
2016年
2015年
2014年
2013年
2012年
2011年
2010年
2009年
2008年
2007年
2006年
2005年
2004年
2003年
BlogPeople
Syndicate this site
FeedBurner(RSS1.0/RSS2.0/Atom)
Counter
これまでのアクセス
Powered by
Movable Type 6.0.3