nikkie-ftnextの日記

イベントレポートや読書メモを発信

back-halfを指定した短縮URLをBitlyのAPIを介して作りたい（curlとPython、2つの方法）

はじめに

📣リョースケええええええええ！ （私は）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を（画面から使うのと同様に）利用して、自動化したいと考えました（怠惰ですねえ）。

アクセストークン取得

使い出すまでは以下が分かりやすかったです。

  1. https://app.bitly.com/settings/api/ にアクセス
  2. アクセストークンを生成
    • 控えておきましょう

curlで実装

2つのエンドポイントを叩きます。

  1. POST /v4/shorten
  2. POST /v4/custom_bitlinks 
% 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も環境にフォーカスします！

  1. BitlyのAPIリファレンスではまだ見つけられていませんが、一般にはslugと呼ぶんじゃないかと思います↩
  2. 過去記事より 週末ログ | みんなのPython勉強会のアーカイブ動画をトリミングしてからYouTubeにアップロードしました #stapy - nikkie-ftnextの日記↩
  3. connpassの「参加者への情報」で見られます↩
  4. 画面から消せるのはback-halfã‚’customizeしていない短縮URLだけでした。実装中に作った短縮URLを片付けていて気づきました↩