Mais conteúdo relacionado
Semelhante a Zenback API 概要資料 (20)
Mais de Six Apart KK (20)
Zenback API 概要資料
- 2. 概要
Zenback（無料版）を、サイトプロバイダサービ
スに組み込むAPIです。
サービサー様用にZenbackアカウントIDとキー
(APIの実行キー)を発行します。そのキーを使っ
て、ユーザ運営の各サイト用のZenbackのスクリ
プトコードを取得/削除できます。
※現在は、ユーザごとの表示内容のカスタマイズ
はできません。
ユーザは管理画面のZenback表示ON/OFFボタン
で簡易にZenbackを自サイトに設置できます。
- 3. API 仕様概要
※仕様詳細は別スライド
ADD API概要
指定のEndpointに対しPOSTで各パラメータ情報（API KEY/アカウン
トID/URL/Signature/Twitter ID）を送信すると、サイトIDと成功/エ
ラーメッセージをJSON形式で返します。
サービサー側では、URL／アカウントID／(APIより取得した)サイト
IDを使いZenbackスクリプトコードを組み立て、サイトの任意の位置
に設置します。また、関連精度を向上するために、Zenbackタグも同
時に設置します。（ZBタグはオプション、ですが強く推奨します）
REMOVE API概要
指定のEndpointに対しPOSTで各パラメータ情報（API KEY/アカウン
トID/サイトID/Signature）を送信すると、Zenback側でブログのNSID
とサイトの登録情報を破棄します。
サービサー側では、サイトに設置したZenbackのスクリプトコードを
削除してください。
- 4. API利用フロー 通常時
ユーザ サービサー Zenback
管理画面よりZenback利用をON ADD API にリクエスト
ブログURLなどを送信:
http://www34.atwiki.jp/test/ APIリクエストを受け取り、
ブログIDを発行して返す
ブログIDを使ってZbコードを組み立
て、サイトテンプレート任意の位置に 取得するブログID例:
設置 89832934667764360
組み立てるZBコード例:
<!-- X:S ZenBackWidget -->（略）
base_uri=http://www34.atwiki.jp/test/
&nsid=
89179659941489196::89832934667764360
ユーザサイトにて （略）<!-- X:E ZenBackWidget
Zenback 利用中
管理画面よりZenback利用をOFF REMOVE API にリクエスト、
ブログ登録情報を破棄
もしくはサイトを削除 サイト設置済みのコードを削除
- 5. API利用フロー スパム検知時
ユーザ サービサー Zenback
特定のサイトをスパム認定し、
メールにて削除依頼
対策（例）：
・ユーザへのアナウンスの有無
サイトにて
Zenback 利用中
・サイトからZBコード削除
・ZBへREMOVE APIコール
ブログ登録情報を破棄
- 6. ADD API 仕様書
Endpoint: https://api.zenback.jp/v1/blog/add/
HTTP method: POST
Response format: JSON
Parameter:
api_key: API Key。指定必須。
nsid: サービサーのzenbackで発行されたアカウントID。指定必須。
このパラメータの指定フォーマットは数字形式で最大19桁まで可能。
url: RSSフィードが取得できるブログのURL。指定必須。
指定できるURL文字列の長さは、256文字まで。
signature: パラメータ(signature自身は除く)の署名 (HMAC-SHA1による署名)。指定必須。
twitter_id: 登録するブログにWidgetとして貼りつけられるFollowボタンに指定するTwitterアカウント。指定オプ
ション。
指定がない場合は、zenbackのデフォルト(zebanckのTwitterアカウント)が指定される。
指定できる文字列の長さは、256文字まで。
Response (HTTP body):
成功: {“status”: {“code”: 0,“msg”: “OK”},“result”: {“blog_nsid”: “103333333333”}}
失敗 {“status”: {“code”: 1,“msg”: „‟No access is allowed”},“result” {}}
HTTP status code:
Success: 200
Error: 400, 401, 500
このAPIで成功したら、Zenback側はブログを登録する。サービサー側は NSIDを受け取るので、Zenbackのス
クリプトコードを生成しテンプレート内任意の箇所に設置。
なお、スクリプトコード(scriptタグ)のNSIDには、”nsid::blog_nsid”の形式で指定すること。例：
89179659941489196::89832934667764360(“::”はエスケープ(%3A%3A)してください。)
- 7. REMOVE API 仕様書
Endpoint: https://api.zenback.jp/v1/blog/remove/ (for Secure)
HTTP method: POST
Response format: JSON
Parameter:
api_key: API Key。指定必須。
nsid: サービサーのzenbackで発行されたユーザーNSID。ユーザーNSIDはユーザーのIDで
ある。指定必須。このパラメータの指定フォーマットは数字形式で最大19桁まで可能。
blog_nsid: zenbackで発行されたブログNSID。ブログNSIDはブログのIDである。指定必
須。add API でブログを登録した際にレスポンスで受け取ったブログNSID(resultオブジェ
クトのblog_nsid)を指定する。このパラメータの指定フォーマットは数字形式で最大19桁
まで可能。
signature: パラメータ(signature自身は除く)の署名 (HMAC-SHA1による署名)。指定必
須。
Response (HTTP body):
成功のケース {“status”: {“code”: 0,“msg”: “OK”},“result”: {}}
エラーのケース {“status”: {“code”: 1,“msg”: „‟No access is allowed”},“result” {}}
HTTP status code:
Success: 200
Error: 400, 401, 500
このAPIで成功したら、サービサーはZenbackのスクリプトコードをテンプレートから外す
- 8. API エラーコード
APIエラーコード(code) APIエラーメッセージ(msg) 説明
0 OK APIのコールが正常に完了
1 No access is allowed APIのコールの許可されていない
2 Missing parameter 何らかの必須パラメータが指定されていない。
指定された何らかのパラメータの中の値が不正の場合。
3 Invalid parameter （例：数字を指定するのにアルファベットが指定されてい
た）
4 Not registered nsid 指定したNSIDがzenbackに登録されていない
5 Not registered blog_nsid 指定したブログNSIDがzenbackに登録されていない
99 Not supported APIリクエストが未サポート
100 Occured internal error zenback 内部でエラーが発生
101 Occured unexpected error zenback で予期しないエラーが発生
- 9. HTTPステータスコード
HTTP ステータスコード 説明
200 ・API リクエストが正常に完了
・必須のパラメータが指定されていない
・パラメータの値が不正
400
・パラメータで指定した nsid が zenback に登録されていない
・パラメータで指定した blog_nsid が zenback に登録されていない
・API リクエストの認証が失敗
401
・オプションで指定するパラメータで空文字が指定されている
404 ・API リクエストが未サポート
500 ・zenback 内でエラー
- 10. Zenback スクリプトコード仕様
<!-- X:S ZenBackWidget --> <script type="text/javascript">
document.write(unescape("%3Cscript")+"
src='http://widget.zenback.jp/?base_uri=TARGET_BLOG_URL&nsid=TARGET_NS
ID&rand="+Math.ceil((new Date()*1)*Math.random())+"'
type='text/javascript'"+unescape("%3E%3C/script%3E")); </script> <!-- X:E
ZenBackWidget -->
TARGET_BLOG_URL
設置サイトのトップページURL
例）http://www.example.com/
wwwの有無は厳密に扱います（例、www有りURLでコード設置した場合にはwww無しで
ページを表示した際、Zenbackは表示されません）
末尾の/は追加してください
TARGET_NSID
ZenbackのアカウントIDとサイトIDを組み合わせて生成。詳細は次ページ参照。
"::"はURLエスケープを行う。 ":" -> "%3A”
例
<!-- X:S ZenBackWidget --><script type="text/javascript">document.write(unescape("%3Cscript")+"
src='http://widget.zenback.jp/?base_uri=http%3A//sixapart.jp/&nsid=99179133006822097%3A%3A99179150723548980&rand="+Math.ceil((ne
w Date()*1)*Math.random())+"' type='text/javascript'"+unescape("%3E%3C/script%3E"));</script><!-- X:E ZenBackWidget -->
- 11. アカウントIDとサイトIDについて
NSIDはアカウントIDとサイトIDを用いて生成す
る、
サイト固有のID。
NSIDの形式
[アカウントID]::[サイトID]
36 bytes ([半角数字17-19文字] + "::" + [半角数字17-
19文字]) (可変)
アカウントIDはサービサー毎に一つ付与
サイトIDはブログごとに異なる
例
99179133006822097::99179150723548980
※（前半がアカウントID）:: (後半がサイトID)
- 12. Zenbackタグの設置
Zenbackタグとは？
Zenbackの記事インデックス用クローラが各
記事のタイトルと本文を正しく検知するため
に、サイトに設置しておくタグです。HTML
のコメントタグを使います。
関連精度向上のため、設置を強く推奨します
詳細は下記ページをご覧ください
http://nanapi.jp/29761/
- 14. APIの諸注意事項
Twitter_idのようなパラメータの指定がオプショ
ンの場合、空文字を指定した場合は、レスポンス
は、HTTP のステータスコードは 401 になり、
zenback のステータスコード(レスポンスで受け
取ったstatusオブジェクト)は(statusオブジェクの
codeプロパティ) 1 になります。
オプション系のパラメータは、指定しない場合は
zenbackのデフォルト値が設定されます。オプ
ション系のパラメータを指定する場合は、デフォ
ルト値以外にしたい場合は、必ず何らかの値を設
定してください。
- 16. 管理画面インターフェース（例）
記事下部にZenbackを表示する
▲
表示する ▼
表示しない
Zenbackの利用規約に同意しました。
※ドロップダウン、ON/OFFトグルなど、排他的に表示/非表示を
選ぶことが出来る設定画面をご用意ください。
※Zenbackの利用規約に同意してもらう項目を追加してください。
利用規約にチェックしないと、利用できないようにしてください。
利用規約リンク先：http://blog.zenback.jp/terms.html
- 17. 設置に関する諸注意事項
（ユーザ向けアナウンス）
Zenbackのコードを貼ってから、「関連記事」「関連
リンク」が表示されるまで、数時間～最大数日ほど
かかる場合があります。ご了承ください。
Zenbackのコードを貼ってから、「Twitter」「はてな
ブックマーク」が表示されるまで、数分～最大数時
間ほどかかる場合があります。ご了承ください。
Twitter、はてなブックマーク、Facebookなどの連携
サービス元で問題が発生して、Zenbackに最新の情報
が表示されない場合があります。ご了承ください。
RSSを出していないサイトではZenbackを貼ることが
できませんので、ご注意ください。
パスワード保護されているサイトではZenbackを貼る
ことができませんので、ご注意ください。
