簽署網址

簽署網址是一個在有人開啟時繪製範本圖片的連結。你可以把它放進 <img> 標籤、電子郵件或 Open Graph 標籤，圖片載入時你的伺服器不需要做任何事。這很適合用於個人化的電子郵件標頭、分享卡片和徽章。

連結中帶有範本 ID、modification 和簽章。擁有這個連結的人都能開啟那張圖片，但沒有人能在不破壞簽章的情況下，變更範本或 modification。

用 SDK 建立簽署網址

SDK 會在你的伺服器上簽署網址，不會發出任何網路請求。

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。

自行建立簽署網址

你可以用任何語言簽署網址。當沒有 SDK 支援你使用的語言，或 SDK 缺少你需要的選項（例如 Go 中的 nocache）時，這很有用。

1. 用 SHA-256 對你的 API 金鑰做雜湊，並以十六進位寫出摘要。這就是 apiKeyHashed。Bannerify 用它來找到你的金鑰，它無法用來簽署任何東西。
2. 從下方的表格蒐集參數。modifications 是 JSON 字串。
3. 依名稱排序參數，然後以 URLSearchParams 產生的格式寫成查詢字串。空格會變成 +，除了英文字母、數字、*、-、. 和 _ 之外的每個字元，都會變成百分比編碼。
4. 以你的 API 金鑰作為密鑰，計算該查詢字串的 HMAC-SHA256，並以十六進位寫出摘要。這就是 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 天。快取鍵是完整的網址，所以 modification 不同，就是不同的圖片。由快取回應的請求不會重新繪製。

被持續請求的圖片會一直留在快取中。快取由 Cloudflare 執行，並由它決定要保留什麼，所以有一段時間沒人請求的副本，可能會在 7 天結束之前就被丟棄。下一個請求會重新繪製圖片，這次繪製會計入你的用量額度。

• 在編輯器中儲存範本，會清除該範本已快取的圖片。以其他方式所做的變更不會清除。
• Settings 的 General 分頁中的 Clear image cache，會清除專案中每個範本已快取的圖片，以及它們從其他網站載入並快取的檔案。
• nocache=true 會略過繪製圖片的快取。每個請求都會繪製新的圖片，回應也不會被儲存。每一次這樣的繪製都會計入你的用量額度。圖層從其他網站載入的快取檔案仍會被使用。

Bannerify 也會快取圖層從其他網站載入的每個檔案。只要該網站 Cache-Control 標頭中的 max-age 允許，就會保留該檔案，但最短 60 秒、最長 7 天。如果網站沒有傳送 max-age，Bannerify 會把檔案保留 1 天。當檔案變更時，請給它新的網址，或使用 Clear image cache。

用量額度與速率限制

一次繪製計為一次生成。由快取回應的請求不會計算。哪些情況會計算，請見用量額度與限制。

簽署網址的繪製有自己的速率限制，每個 API 金鑰每 10 秒 100 個請求。由快取回應的請求不計入。超過限制時，請求會回傳 RATE_LIMITED。

確保安全

• 請在你的伺服器上簽署。簽章會用到你的 API 金鑰，所以簽署用的程式碼不能在瀏覽器或你發行的應用程式中執行。
• 這個網址可以放心分享。它包含簽章和你金鑰的雜湊值，兩者都無法用來簽署另一個網址。
• 擁有網址的人可以隨意開啟任意次。網址永遠不會過期，而每一次沒有命中快取的繪製，都會計入你的用量額度。
• modification 會以純文字放在網址中。請不要在其中放入私人資料。
• 若要讓某個金鑰簽署的所有網址都失效，請在 API Keys 頁面刪除該金鑰。

疑難排解

請求失敗時，圖片標籤會顯示破圖。請在瀏覽器分頁中開啟網址來讀取錯誤。