クイック スタート ガイド
イントロダクション
ウェブサイトやアプリケーションから Data API を使う方法について解説します。各エンドポイントや、リソースについての詳細については、API リファレンスをご覧ください。
ユーザー認証とアクセストークン
公開されていない記事の情報を取得する場合や、新しく記事を投稿する場合はユーザー認証が必要です。もちろん、リクエストに対してユーザーが適切な権限を持っている必要があります。ユーザー認証は、Movable Type の管理画面と同様にユーサー名とパスワードを用いて行われます。
また、認証が必要なリクエストをおこなう場合、ユーザー認証とは別にリクエストごとに「アクセストークン」と呼ばれる生存期間の短いトークンを付加する必要があります。
Data API でユーザー認証を行なう（サインイン画面を利用する）
Web ブラウザから Data API を利用する場合には、authorization エンドポイントにアクセスして、サインイン画面を経由した認証を行います。
リクエスト
GET http(s)://path/to/mt-data-api.cgi/v5/authorization?clientId=<YOUR-CLIENT-ID>&redirectUrl=<REDIRECT-TO-URL>リクエスト パラメータ
- clientId（必須）
- アプリケーション固有の任意のキーを指定します。アルファベット、(_)アンダースコア、(-)ダッシュ、で構成された任意の文字列を指定できます。
- redirectUrl（必須）
- サインインに成功したとき、遷移するリダイレクト先のURLを指定します。
レスポンス
サインイン画面が表示され、サインインに成功すると redirectUrl で指定された URL にリダイレクトされます。
Data API でユーザー認証を行なう（直接サインインする）
Web ブラウザではなく、アプリケーションから認証を行う場合には、authentication エンドポイントを利用します。このエンドポイントによるユーザー認証は、サインインの処理と同様に、username と password による認証を行います。
リクエスト
POST http(s)://path/to/mt-data-api.cgi/v5/authenticationリクエスト パラメータ
パラメータは、リクエストのボディとして送信します。従って、application/x-www-form-urlencodedまたは、multipart/form-data 形式である必要があります。
- username（必須）
- サインインするユーザーのユーザー名を指定します。
- password（必須）
- サインインするユーザーのパスワードを指定します。v3 からは、CMS のログインパスワードではなく、Web サービス パスワードを指定します。
- remember
- 1 を指定すると、ユーザーのログインセッションは、サインアウトするまで有効になります。
- clientId
- アプリケーション固有の任意のキーを指定します。アルファベット、(_)アンダースコア、(-)ダッシュ、で構成された任意の文字列を指定できます。
- mtDataApiLoginMagicToken
- セッションクッキーの名前を指定できます。通常は、指定する必要はありません。
レスポンス
username と passsword の組み合わせが正しい場合、sessionId, accessToken が取得できます。
{
"accessToken": "0t60z2zrz89WSfi8euUl21VZ3LOG4tc1pYWhzZLj",
"sessionId": "ThRsb2XwYvFs93gvmbUeF3nu3JDIEIYP8polopI6",
"expiresIn": 3600,
"remember": false
}サンプルコード (JavaScript)
ここでは、jQuery を利用した JavaScript のサンプルコードを紹介します。
$.ajax({
url: "http://example.com/mt/mt-data-api.cgi/v5/authentication",
type: "POST",
dataType: "json",
data: {
'username': 'your-username',
'password': 'your-password',
'clientId': 'test'
}
}).done(function(data){
alert(data.accessToken);
});アクセストークンを取得する
前述のとおり、認証が必要なリクエストを行う場合は、アクセストークンをリクエスト・ヘッダーに付加してリクエストを実行する必要があります。アクセストークンは、AccessTokenTTL 環境変数で指定された秒数（初期値: 3600秒 = 1時間）の間だけ利用できるワンタイムトークンです。
生存期間中は、同じトークンを利用することができますが、できるだけリクエスト単位で新しいトークンを取得することを推奨します。
リクエスト
POST http(s)://path/to/mt-data-api.cgi/v5/tokenリクエスト パラメータ
パラメータは、リクエストのボディとして送信します。従って、application/x-www-form-urlencodedまたは、multipart/form-data 形式である必要があります。
- clientId
- サインインの際に使用した clientId と同じ値を指定します。X-MT-AuthorizationにsessionIdを指定する場合は、clientId を指定する必要はありません。
レスポンス
有効なセッションである場合、新しいアクセストークンを取得できます。
{
"accessToken": "UQddkGoFAR0PlqLiaatJGe22HkqxA3pTrNpT2DjI",
"expiresIn": 3600
}サンプルコード (JavaScript)
ここでは、jQuery を利用した JavaScript のサンプルコードを紹介します。
var sessionId = "MTAuth sessionId=BKuU8Pc25oZRCuaNDijoO8RFS1itBmPaVM7LgELH";
$.ajax({
url: "http://example.com/mt/mt-data-api.cgi/v5/token",
type: "POST",
dataType: "json",
headers: {
'X-MT-Authorization': sessionId
}
}).done(function(data){
alert(data.accessToken);
});アクセストークンを付加したリクエストを行なう
アクセストークンは、X-MT-Authorization リクエストヘッダーに MTAuth accessToken=<ACCESS_TOKEN>という形式で指定します。
サンプルコード (JavaScript)
ここでは、jQuery を利用した JavaScript のサンプルコードを紹介します。
// sessionId をもとに新しいアクセストークンを取得します。
var sessionId = "MTAuth sessionId=BKuU8Pc25oZRCuaNDijoO8RFS1itBmPaVM7LgELH";
$.ajax({
url: "http://example.com/mt/mt-data-api.cgi/v5/token",
type: "POST",
dataType: "json",
headers: {
'X-MT-Authorization': sessionId
}
}).done(function(data){
// アクセストークンをヘッダーに付加して、非公開の記事を取得します。
var accessToken = "MTAuth accessToken=" + data.accessToken;
$.ajax({
url: "http://example.com/mt/mt-data-api.cgi/v5/sites/1/entries/1",
type: "POST",
dataType: "json",
headers: {
'X-MT-Authorization': accessToken
}
}).done(function(entries){
alert( entries.items[0].title);
})
});詳説 Data API シリーズ
各エンドポイントについて、具体的なサンプルコード付きで解説しています。こちらも併せてご覧ください。
