はじめに
📣リョースケええええええええ！ （私は）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も環境にフォーカスします！
