Codin’ In The Free World

2008-08-15

[] URLを埋め込みコンテンツに変換するoEmbedの仕様

http://oembed.com/

eEmbedというのは、あるリソースのURL(例えばFlickrの特定の写真のページのURL)を

サードパーティ上で、写真自体の埋め込みに変換したいときに、

埋め込みに必要なパラメータを取得するためのプロトコルみたいです。


mixiのデコリンク機能がイメージとして近いかもしれません。

http://alpha.mixi.co.jp/blog/?p=38


宮川さんが既にPerl Moduleにしてますね。

http://search.cpan.org/~miyagawa/Web-oEmbed-0.01/


仕様を適当に訳したので載せておきます。

Spec

oEmbedは、サードパーティのサイトのURLを埋め込み表現するためのフォーマットです。

これによって、ユーザーがそのリソースへのリンクをポストしたときに、

リソースをパースすること無しに、

写真や動画のような埋め込みコンテンツを表示することができるようになります。

1. Quick Example

コンシューマ(例えばPownce)は次のようなリクエストを生成する。

http://www.flickr.com/services/oembed/?url=http%3A//www.flickr.com/photos/bees/2341623661

プロバイダ(例えばFlickr)は次のようにレスポンスを返します。

{
"version": "1.0",
"type": "photo",
"width": 240,
"height": 160,
"title": "ZB8T0193",
"url": "http://farm4,static.flickr.com/3123/2341623661_7c99f48bbf_m.jpg",
"author_name": "Bees",
"author_url": "http://www.flickr.com/photos/bees/",
"provier_name": "Flickr",
"provider_url": "http://www.flickr.com/"
}

コンシューマは、Flickrの写真ページにリンクするURLを、

コンシューマのサイト上で埋め込むための構造化されたデータに変換できます。

2. Full Spec

この仕様は、三つのパートに分けられる。

コンフィギュレーションとコンシューマーのリクエスト、それから

プロバイダーのレスポンスです。

oEmbed交換はコンシューマとプロバイダの間で起こります。

コンシューマは、写真や動画のようなサードーパーティ上のリソースを、

コンシューマ自身のサイト上で埋め込み表現したいと考えています。

2.1 Configuration

oEmbedのためのコンフィギュレーションは非常にシンプルです。

プロバイダは一つ以上のURLスキームとAPIのエンドポイントを

設定しなければなりません。

URIスキームはサービスに提供される各URLが埋め込み表現を持っていることを示します。

APIのエンドポイントは、コンシューマがどこにリクエストを飛ばせばよいかを示します。

例えば

URL Scheme

http://www.flickr.com/photos/*

API Endpoint

http://www.flickr.com/services/oembed/

URLスキームは一つ以上のワイルドカード(*)を含んでもよいです。

ワイルドカードはドメインパートやパスの部分のどちらに含まれていてもよいです。

ドメインパート内では、サブドメインの部分でのみ、使えます。

ワイルドカードはHTTP(S)のようなプロトコルスキームでは使えません。

APIのエンドポイントは必ずHTTPのエンドポイントのURLになっていなければ

なりません(HTTPSは駄目)。

次の仕様を満たしていなければなりません。

2.2 Consumer Request

APIエンドポイントへ送られるリクエストは、HTTP GETでなければなりません。

全ての属性は、クエリーパラメータで表現します。

パラメータはURLエンコードされなければなりません。

次のクエリーパラメータが仕様として定義されています。

1. url(必須)

埋め込みたい情報を取得するためのURL

2. maxwidth

埋め込みたいリソースの最大幅。

いくつかのリソースタイプのみに適用される。

これをサポートするリソースタイプの場合、

プロバイダは指定された値を尊重しなくてはならない。

3. maxheight

maxwidthと同じように。最大の高さ。

4. format

レスポンスのフォーマット。特に指定されなければ、

プロバイダはどのフォーマットで返してもいい。

フォーマットを指定された場合は、指定されたフォーマットで

データを返すか、対応してなければエラーを返す。


http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/

http://flickr.com/services/oembed?url=http%3A//clickr.com/photos/bees/2362225867/&maxwidth=300&maxheight=400&format=json

プロバイダはフォーマットを、クエリーストリングではなく、

エンドポイントURLで指定できるようにしてもよい。

例:

URL Scheme:

http://www.flickr.com/photos/*

API XML endpoint

http://www.flickr.com/services/oembed.xml

API JSON endpoint

http://www.flickr.com/services/oembed.json

この場合、フォーマットパラメータ必要とされず、つけても無視される。

プロバイダがURLとAPIエンドポイントを発行するときに、

プロバイダが暗黙にフォーマットを決定するのか、

引数として渡すことを要求するのかを明らかにしなければならない。

2.3 Provider Response

プロバイダから返されるレスポンスはJSONかXMLになります。

どちらのフォーマットでも、レスポンス中のContent-Typeヘッダに

紐づけられたmime-typeを入れておかなくてはなりません。

2.3.1 JSON response

JSONでレスポンスするときはapplication/jsonのmime-typeで返します。

Consumerがformatクエリでjsonを指定したときなどに、JSONレスポンスが返されます。

{
  "foo": "bar",
  "baz": 1
}

テキストはUTF-8でエンコードされてること

2.3.2 XML resopnse

XMLレスポンスはtext/xmlのmime-typeで返すこと。

Consumerはformatでxmlを指定したときなどにXMLフォーマットのレスポンスを返す。

レスポンスのbodyはoembedと呼ばれるルートエレメントと、

それにぶらさがる子エレメントで構成される。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<oembed>
  <foo>bar</foo>
  <baz>1</baz>
</oembed>

テキストはUTF-8でエンコードされること。

値はエスケープされたPCDATAでなくてはならない。

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
  <html>&lt;b&gt;awesome!&lt;/b&gt;</html>
</oembed>

2.3.4 Response Parameters

レスポンスはphoto, videoのようなリソースタイプを指定することが出来る。

どちらのタイプもそれに紐づいた独自のパラメータを持っている。

次に挙げるレスポンスパラメータは全てのレスポンスタイプについて有効である。

type(必須)resouce type。photoとかvideoとか。
version(必須)oEmbedのバージョン。現在なら"1.0"
titleリソースを説明するタイトル
author_nameリソースのauthor/ownerの名前
author_urlauthor/ownerのURL
provider_nameリソースプロバイダの名前
provider_urlリソースプロバイダのURL
cache_ageそのリソースのキャッシュのライフタイム。Consumerはこの値を使うか使わないか選択できる。
thumbnail_urlリソースのサムネイル画像を表すURL。サムネイルはmaxwidthとmaxheightの値を尊重しなければならない。このパラメータをつける場合は、thumbnail_widthとthumbnail_heightもつけること。
thumbnail_widthサムネイルの幅
thumbnail_heightサムネイルの高さ

プロバイダはこのドキュメントで定義されてないパラメータを含めてもよい。

ただし、これまでの値と同じようにキーバリューのペアでデータを表現すること。

コンシューマはそれらの独自定義のパラメータを無視するかどうか選択してもよい。

コンシューマは自分が理解できないパラメータは無視しなければならない。

2.3.4.1 photo

resouce typeがphotoのときのためのパラメータ

url(必須)画像のリソースURL。コンシューマがこの値をHTMLのimgエレメントに挿入できるようにしておくべき。HTTP(s)の有効な値。
width(必須)urlで指定される画像の幅のピクセル数
height(必須)urlで指定される画像の高さのピクセル数

各値はmaxwidthやmaxheightに従うこと

2.3.4.2 video

再生可能な動画を表すタイプ。

html(必須)動画プレイヤーを埋め込むために必要なHTML。HTMLはpaddingやmarginを含むべきではない。ConsumerはXSSを避けるためにドメイン外のiframeを利用してHTMLを読み込んでもよい。
width(必須)HTMLを表示するために必要な幅のピクセル数
height(必須)HTMLを表示するために必要な高さのピクセル数

maxwidthやmaxheightに従わなくてはならない。

もしプロバイダが、埋め込みプレイヤーではなくて、サムネイル表示を

コンシューマに望むのなら、videoのかわりにphotoレスポンスタイプで返すべき。

2.3.4.3 link

プロバイダはこのタイプを使うことで、photoで使ったurlや、videoで使ったhtmlといったパラメータ無しでも、

汎用的な埋め込みデータを返すことが可能になる。(titleとかauthor_nameとか)。

コンシューマはオリジナルリクエストで定義されたURLを使って、リソースにリンクしてもよい。

2.3.4.4 rich

ほかのカテゴリーに含まれないリッチなHTMLコンテンツのために使われる

html(必須)リソースを表示するために必要なHTML。paddingやmarginはつけるべきではない。コンシューマはXSSを避けるために別ドメインのiframeで読み込んでもよい。マークアップは正しいXHTML1.0 Basicであるべき
width(必須)HTMLを表示するための幅のピクセル数
height(必須)HTMLを表示するための高さのピクセル数
2.3.5 Errors

プロバイダはエラーをHTTP status codeで返すべき。

次のステータスコードがoEmbedの仕様の一部として定義されている

404 not FoundプロバイダはリクエストされたURLのためのレスポンスを持っていない。
501 Not Implementedプロバイダはリクエストされたフォーマットでレスポンスを返せない。例えばformat=xmlとしてリクエストされたが、プロバイダがXMLレスポンスに対応してないときなど。ただし、プロバイダはJSONとXMLの両方に可能な限り対応するよう推奨される。
401 Unauthorized指定されたURLはプライベートなリソースを含んでいる。Consumerはその他の埋め込み情報のかわりに、リンクを直接はって、アクセスコントロールについてはプロバイダにまかせるべき。

3 Security considerations

Providerは自由にURLを定義することを許されているが、コンシューマはそれらのURLを

フィルターしたい場合がある(http, https, mailto以外を取り除く等)。

フィルタリングしないと、javascript:... といったURLが渡されたときにXSS脆弱性となってしまう。

HTMLを表示する場合、XSSを防止するために、

Consumerは別ドメインによるiframeを用意してそこにHTMLを埋め込むとよい。

そうすればconsumerのドメインのクッキーにアクセスできない

4 Discovery

oEmbedのプロバイダは(X)HTMLドキュメントのヘッダにエレメントを挿入することによって

ディスカバリーをサポートするかどうかを選択できる。

<link rel="alternate" type="application/json+oembed"
  href="http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/236222586"
  title="Bacon Lollys oEmbed Profile" />
<link rel="alternate" type="text/xml+oembed"
  href="http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/236222586"
  title="Bacon Lollys oEmbed Profile" />

href属性に含まれるURLはoEmbedのエンドポイントにurlパラメータやformatパラメータが

つけられたものになる。

他のリクエストパラメータもこのURLに含まれるべきである。

type属性は必ず含まれなければならない。

JSONの場合は application/json+oembed, XMLの場合は text/xml+oembedになる。

スパム対策のためのダミーです。もし見えても何も入力しないでください
ゲスト


画像認証