はじめに
どうも、よく訓練された PHPer のけんつです。
突然ですが、みなさん Youtube や Instagram などのメディア共有サイトの情報で特にコンテンツの埋め込みに必要な情報だけ欲しいときに
わざわざデベロッパー登録して、コンシューマーキー等を取得してAPIを叩くのって面倒じゃね？と思うことありませんか？
今日はそんなあれこれを手軽に便利にしてしまう「oEmbed」というものについて書こうと思います。
oEmbed とは
oEembed については以下のサイトがドキュメントを公開している。
じゃあ、oEmbed とは何かというと「コンテンツ共有サイトの情報を埋め込み可能な形式で提供するAPI」のことを指していて。
これは開発者登録等をしなくとも使用することができるためコンテンツ情報だけを使いたい時に非常に便利なもの。
この後、詳しい規格について記述していこうと思いますが「そんなんしらん、使えればok」という人は以下の例を見てください。
Quick Start
今回は Youtube を例に説明していく。
www.youtube.com
上記の動画を題材にする。
まず、oEmbed で必要になるのはそのコンテンツのURL。
今回で言えば
https://www.youtube.com/watch?v=SX_ViT4Ra7k
これ。
youtube の url に /watch というルーティングがあり、 クエリストリングで動画IDが付与されているこれ。
コンテンツのURLがわかれば次にやることは youtube の oEmbed エンドポイントにリクエストを投げるだけ。
Youtube の oEmbed エンドポイントは
https://www.youtube.com/oembed
↑これ。
それのエンドポイントに url 情報と format 形式をクエリストリングで指定してリクエストを送ると json が返ってくる。
※本当はクエリストリングの部分は url encode が必要。
{ "width": 480, "version": "1.0", "author_url": "https://www.youtube.com/user/08yakari", "provider_name": "YouTube", "type": "video", "provider_url": "https://www.youtube.com/", "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/SX_ViT4Ra7k?feature=oembed\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>", "thumbnail_url": "https://i.ytimg.com/vi/SX_ViT4Ra7k/hqdefault.jpg", "thumbnail_width": 480, "title": "米津玄師 MV「Lemon」", "thumbnail_height": 360, "author_name": "米津玄師", "height": 270 }
あとは json を煮るなり焼くなり好きにするといい感じにできる。
ひとつ言うなら、 html メンバーの値は直接埋め込み可能な iframe 形式となっている。
なんならサムネイルのURLもついてきているのでスゴク便利。
oEmbed の規格
使うだけならあれでいいんだけど、それじゃ気がすまねぇ！！っていう人のためにしっかりと規格についてもまとめていきたい。
Consumer Request
oEmbed のエンドポイントに送るリクエストには必要なパラメータと形式が存在する。
まず大前提としてリクエストはエンドポイントに対してGETリクエストである必要があり、全てのパラメータは RFC 1738 に準拠した形式で URL Encode された状態で無いといけない。
その大前提の元に以下のパラメータをリクエストに含めることができる。
- url (require)
これは情報を取得したいコンテンツのURL。
- maxwidth (optional)
埋め込みリソースの最大幅。一部のリソースタイプ（以下に記載）にのみ適用される
- maxheigth (optional)
埋め込みリソースの最大高さ。一部のリソースタイプ（以下に記載）にのみ適用される。
- format (optional)
レスポンス形式を指定する。
この中で max*** 系 はあまり使わないが、注意が必要なものが format になる。
これは大抵 json or xml を指定するが存在しないものを選択するとエラーが返ってくる。
なので、どちらかを指定してリクエストを投げるのが良い。
Provider Response
ここからはレスポンスに関すること。
Response parameters
json に含まれるパラメータについて。
- type (required)
コンテンツの種別を表す、video, image などがある
- version (required)
oEmbed のバージョンを表す、今は1.0
- title (optional)
コンテンツのタイトル
- author_name (optional)
コンテンツの作者等。
- author_url (optional)
コンテンツの作者のURL
- provider_name (optional)
コンテンツを提供しているヤツの名前、youtube などサービス名がおおい
- provider_url (optional)
これもコンテンツを提供しているサービスのURL
- cache_age (optional)
推奨されるコンテンツのキャッシュ有効期間。
- thumbnail_url (optional)
サムネイルを管理しているURL
- thumbnail_width (optional)
サムネイルのサイズ
- thumbnail_height (optional)
サムネイルのサイズ
この中で特に注意が必要なのが type である。
これによって更に require なパラメータが増えたり、iframe の埋め込みコードがあったりなかったりしてしまう。
Errors
渡したurlパラメータの値となるurlにコンテンツが無い場合に返る
レスポンスを要求された形式で返せない場合に返る。
- 401 Unauthorized
指定されたURLには、プライベート（非公開）リソースが含まれている場合に返る。
Security considerations
oEmbed 対応のAPIを提供する場合に対応するURLについて。
URL スキームを http, https, mailto などに限定しないと、javascript:... などXSSの攻撃に利用されてしまう点に注意
おわりに
oEmbed は、コンテンツ情報をひっぱってくる際にかなり便利なのでぜひ使っていきたい。
ただ、コンテンツの説明などは手に入らない場合があるのでそういうときは黙って開発者登録などしてAPIを使うしかない。