署名付き URL

署名付き URL は、誰かが開いたときにテンプレートの画像を描画するリンクです。<img> タグ、メール、Open Graph タグに入れられ、画像が読み込まれるときに、サーバーは何も処理しません。パーソナライズしたメールのヘッダー、シェアカード、バッジに便利です。

リンクには、テンプレート ID、modification、署名が含まれます。リンクを持っている人は、その画像をそのまま開けますが、署名を壊さずにテンプレートや modification を変更することは、誰にもできません。

SDK で署名付き URL を作成する

SDK は、サーバー上で URL に署名します。ネットワークリクエストは送りません。

const url = await bannerify.generateImageSignedUrl("tpl_xxx", {
  modifications: [{ name: "headline", text: "Hello, Ada" }],
})

url = client.generate_image_signed_url(
    "tpl_xxx",
    modifications=[{"name": "headline", "text": "Hello, Ada"}],
)

$url = $client->generateImageSignedUrl('tpl_xxx', [
    'modifications' => [['name' => 'headline', 'text' => 'Hello, Ada']],
]);

url, err := client.GenerateImageSignedURL("tpl_xxx", &bannerify.CreateImageOptions{
    Modifications: []bannerify.Modification{{Name: "headline", Text: ptr("Hello, Ada")}},
})

各 SDK のオプションは、それぞれのページにまとめています: JavaScript、Python、PHP、Go。

署名付き URL を自分で作成する

署名付き URL は、どの言語でも作成できます。使っている言語の SDK がない場合や、Go の nocache のように、必要なオプションが SDK にない場合に便利です。

1. API キーを SHA-256 でハッシュ化し、ダイジェストを 16 進数で書き出します。これが apiKeyHashed です。Bannerify はこれを使ってキーを探しますが、これで何かに署名することはできません。
2. 下の表からパラメーターを集めます。modifications は JSON 文字列です。
3. パラメーターを名前でソートし、URLSearchParams が生成する形式のクエリ文字列として書き出します。スペースは + になり、英字、数字、*、-、.、_ 以外のすべての文字は、パーセントエスケープされます。
4. そのクエリ文字列の HMAC-SHA256 を、API キーをシークレットとして計算し、ダイジェストを 16 進数で書き出します。これが sign です。
5. クエリ文字列に sign を追加します。

import { createHash, createHmac } from "node:crypto"

const apiKey = process.env.BANNERIFY_API_KEY!

const params = new URLSearchParams({
  templateId: "tpl_xxx",
  apiKeyHashed: createHash("sha256").update(apiKey).digest("hex"),
  modifications: JSON.stringify([{ name: "headline", text: "Hello, Ada" }]),
  nocache: "true",
})
params.sort()
params.set("sign", createHmac("sha256", apiKey).update(params.toString()).digest("hex"))

const url = `https://api.bannerify.co/v1/templates/signedurl?${params}`

パラメーター

キャッシュ

Bannerify は、描画した画像をエッジキャッシュに最大 7 日間保持します。キャッシュキーは URL 全体のため、modification が異なれば、別の画像になります。キャッシュが応答したリクエストでは、再描画されません。

繰り返しリクエストされる画像は、キャッシュに残り続けます。キャッシュは Cloudflare が運用し、何を保持するかも Cloudflare が決めるため、しばらく誰もリクエストしなかったコピーは、7 日が経つ前に破棄されることがあります。次のリクエストで画像が再描画され、その描画はクォータに数えられます。

• エディターでテンプレートを保存すると、そのテンプレートのキャッシュ済みの画像が消去されます。それ以外の方法で行った変更では、消去されません。
• Settings の General タブにある Clear image cache は、プロジェクトのすべてのテンプレートのキャッシュ済みの画像と、それらが他のサイトから読み込むキャッシュ済みのファイルを消去します。
• nocache=true は、描画した画像のキャッシュをスキップします。リクエストのたびに新しい画像が描画され、レスポンスは保存されません。これらの描画は、1 つずつクォータに数えられます。レイヤーが読み込むキャッシュ済みのファイルは、引き続き使われます。

Bannerify は、レイヤーが他のサイトから読み込む各ファイルもキャッシュします。そのサイトの Cache-Control ヘッダーの max-age が許す期間、ただし最短 60 秒、最長 7 日間、ファイルを保持します。サイトが max-age を送らない場合は、ファイルを 1 日間保持します。ファイルが変わったときは、新しい URL を付けるか、Clear image cache を使ってください。

クォータとレート制限

描画は、1 回の生成として数えられます。キャッシュが応答したリクエストは数えられません。何が数えられるかは、クォータと制限にまとめています。

署名付き URL の描画には、API キーごとに 10 秒間に 100 リクエストという、独自のレート制限があります。キャッシュが応答したリクエストは、これに含まれません。制限を超えると、リクエストは RATE_LIMITED を返します。

安全に使う

• 署名は、サーバーで行います。署名には API キーを使うため、署名のコードをブラウザーや、配布するアプリで実行してはいけません。
• URL は、共有しても安全です。URL には署名とキーのハッシュが含まれますが、どちらも別の URL に署名することはできません。
• URL を持っている人は、何度でも開けます。URL に有効期限はなく、キャッシュに当たらない描画は、すべてクォータに数えられます。
• modification は、プレーンテキストとして URL に含まれます。非公開のデータを入れないでください。
• キーが署名したすべての URL を無効にするには、API Keys ページでそのキーを削除します。

トラブルシューティング

リクエストが失敗すると、画像タグには壊れた画像が表示されます。エラーを読み取るには、ブラウザーのタブで URL を開いてください。