はじめに
📣リョースケええええええええ! (私は)nikkieです。
URLを短縮できるサービスBitly。
Web APIも公開されています。
APIを使ってback-half(http://bit.ly/XXX
のXXX
の部分1)を指定したURLを作る方法をアウトプットします。
目次
そもそもことの始まりは
背景
「back-halfを指定した短縮URLをBitlyのAPIを介して作りたい」は、みんなのPython勉強会のスタッフ活動2の一環です。
勉強会ではhttp://bit.ly/stapy94awesome
のような短縮URLを使っています3。
用語の整理
http://bit.ly/stapy94awesome
のような短縮URLですが、Bitlyの用語では「Short link with a custom back-half」と呼ぶようです。
https://support.bitly.com/hc/en-us/articles/115001626408
- ドメインは
bit.ly
- back-half(「URLの後ろ半分」だと思います)を
stapy94awesome
とcustomize- back-halfを指定しないと、Bitlyがいい感じにランダムな文字列で付けてくれます
回数制限はありますが、無料でも利用できます。
今回試す中で知ったのですが、「Short link with a custom back-half」は(少なくとも無料プランでは画面操作で)消せないようです(一覧から隠すことはできます)4。
画面操作編
- Bitlyにログイン
- 「Create new」 > 「Link」
- 以下を入力
- 「Destination」に短縮したい長いURL
- 「Custom back-half」に指定したい文字列
Web APIを使った自動化編
画面操作でできるのなら、公開されているAPIを(画面から使うのと同様に)利用して、自動化したいと考えました(怠惰ですねえ)。
アクセストークン取得
使い出すまでは以下が分かりやすかったです。
- https://app.bitly.com/settings/api/ にアクセス
- アクセストークンを生成
- 控えておきましょう
curl
で実装
2つのエンドポイントを叩きます。
- POST
/v4/shorten
- https://dev.bitly.com/api-reference/#createBitlink
- back-halfはランダムな文字列で短縮
- 2の呼び出しでidを使う
- POST
/v4/custom_bitlinks
- https://dev.bitly.com/api-reference/#addCustomBitlink
- idを指定してback-halfをcustomize
% curl -H "Authorization: Bearer ${BITLY_ACCESS_TOKEN}" \ -H 'Content-Type: application/json' \ -d '{"long_url": "https://nikkie-ftnext.hatenablog.com/entry/the-solitary-castle-in-the-mirror-2023-june"}' \ https://api-ssl.bitly.com/v4/shorten | jq . # 返り値のJSONの.idを後続の呼び出し(-dの.bitlink_id)で使用 % curl -H "Authorization: Bearer ${BITLY_ACCESS_TOKEN}" \ -H 'Content-Type: application/json' \ -d '{"custom_bitlink": "bit.ly/nikkie-api-practice", "bitlink_id": "bit.ly/3WRejsH"}' \ https://api-ssl.bitly.com/v4/custom_bitlinks | jq .
ランダムな文字列によるback-halfのエイリアスとして、カスタマイズしたback-halfも持たせるということでしょうかね。
Pythonスクリプト
Python 3.10.9、標準ライブラリだけで実装しています。
# 環境変数 BITLY_ACCESS_TOKEN を設定済み % python create_custom_bitlink.py \ https://nikkie-ftnext.hatenablog.com/entry/the-solitary-castle-in-the-mirror-disk-advent-2023-start \ kagami-advent-2023
勉強会運営自動化リポジトリにも入れました。
苦労話
チュートリアルのドキュメントの通りにいかず、ハマりました。
「Creating custom links」には以下のようにあります。
To customize the back-half of a link, you'll perform an additional PATCH call.
PATCH /v4/custom_bitlinks/{custom_bitlink}
ですが、叩いてみるとエラーが返ってきます。
% curl -H "Authorization: Bearer ${BITLY_ACCESS_TOKEN}" \ -H 'Content-Type: application/json' \ -d '{"bitlink_id": "bit.ly/nikkie-api-practice"}' \ -X PATCH https://api-ssl.bitly.com/v4/custom_bitlinks/bit.ly/3WRejsH | jq . { "message": "NOT_FOUND", "resource": "custom_bitlinks", "description": "What you are looking for cannot be found." }
このエラーの現時点の理解ですが、
- PATCHなので1つ以上custom bitlink(リソース)が存在している必要がある
- にもかかわらず、0個なのでnot foundエラー
ということでしょうか。
ヒントになったのは、他の言語で書かれたクライアントライブラリを眺めていて。
GitHub - opsmatters/bitly-java-api: Java client library to execute operations on URLs using the Bitly API.
これを見て、そもそもPATCHするエンドポイントがPREMIUM(おそらく有料プラン限定の意)と気付くとともに、POSTしてcustom bitlinkを1つ作る(PREMIUMでない)エンドポイントの存在に気付きました!
終わりに
curlやPythonで、Bitlyの短縮URL(ただし、back-halfを指定したもの)を作る方法をアウトプットしました。
2つのエンドポイントを順に叩くことで実現できます。
チュートリアルの通りに進めてもエラーとなったことでハマりましたが、/v4/custom_bitlinks
へのPOSTに気づいて、やりたいことを実現できました🙌
次回のみんなのPython勉強会は6/15(木)です。
6月は環境月間らしく、stapyも環境にフォーカスします!