Zenn
📣

SUZURI APIを用いたアプリケーションを作る時に細かなTips集

2024/12/14に公開
SUZURI API
suzuri
tech

🎅GMOペパボ エンジニア Advent Calendar 2024の14日目です。

13日目はOCRとLeafletでイベント会場の目的地が一目で分かるマップを作ったでした。即売会やイベントでクリエイターさんのブースをパンフレットから探すのは大変なので、フォローしているアカウントを元に、自動でマップにピンが立つのはとても便利でした〜!

この記事では、SUZURI APIを用いたアプリケーションを作る時に細かなTipsを書いていきます。

SUZURIとSUZURI APIについて

SUZURI APIの前にSUZURIを知らない方向けに大まかなサービス内容を紹介します。

SUZURIはグッズ作成・販売、デジタルコンテンツ販売、コミッションを行えるサービスです。
グッズ作成・販売では、受注生産のため1点からのグッズ販売ができます。

SUZURI APIはSUZURIの一部の機能を外部のアプリケーションから利用できるものです。
できることしては、

  • グッズの作成、削除
  • グッズの検索
  • ズッキュン(お気に入り)の登録と削除
    などです。

利用料金はなく、SUZURIユーザーであれば誰でもお使いいただけます。

SUZURI APIに利用方法と差異

SUZURI APIは二つの方法で利用できます。

  1. アプリケーションで1つのToken を使って、APIを利用
  2. OAuthを使って、APIを利用
    https://suzuri.jp/developer/documentation/v1#auth

今回はSUZURI APIではOAuth認証を利用しました。利用方法による主な違いは以下の通りです。

1.Tokenを使ったAPI利用 2.OAuthを使ったAPI利用
グッズ作成時の販売ショップ Tokenを発行したユーザー(=アプリケーションの運営者)のショップ 利用ユーザーにショップ
取得できる商品情報 公開されたグッズ + Tokenを発行したユーザー(=アプリケーションの運営者)の非公開グッズ 公開されたグッズ + アプリユーザーの非公開グッズ

どちら方法で利用するかは、以下に2ポイントで決めています

  • トリブンのもらう人が誰か
  • アプリユーザーの非公開グッズを取得したいか

具体的にどんなふうに選んでいるかご紹介します。
https://x.com/yukyu30/status/1859264148657578337
以上のようなPR画像生成ツールを作った時には、OAuthを使ったAPI利用を採用しました。理由としては以下の通りです。

  • グッズを作成しないのでトリブンが発生しない
  • セールに合わせてグッズを公開するというアプリユーザがいるため、非公開グッズを取得したい

OAuthを使ったAPI利用では、アプリケーションの登録が必要です。登録を行うと、
OAuth Client idとOAuth Client Secretが発行されます。

Callback URLは、httpsである必要があるため、自分はOrbstackなどのツールを使って、Local環境にhttpsでアクセスできるようにしています。

次の章からは実際にSUZURI APIを使うときのTipsを紹介します。

グッズ画像の取得目的では、sampleImageUrlが使いやすい

グッズの画像を表示する時には、APIのレスポンスに含まれる、ProductのsampleImageUrl、pngSampleImageUrlを、imgタグのsrcに指定しするのが一番簡単です。

sampleImageUrlではwebp画像で、pngSampleImageUrlではpng画像が取得できます。

imageUrlなどでは、各パラメータを自分たちで置き換える必要があるため、size指定や色指定などのこだわりがある時に使います。

商品ページへの遷移にはsampleUrlが使いやすい

グッズの詳細ページに遷移するには、Productに含まれるsampleUrlが一番簡単です。
クリック時の遷移先にsampleUrlを指定すると、SUZURIのグッズ詳細ページに遷移できます。

次は、これらを組み合わせた実践的な内容を紹介します。

画像をアップロードして、グッズのプレビューしたいときにもProductを一回作る

ユースケースとしてよくある画像アップロードして、プレビューして購入を決めるというフローをSUZURI APIで実現する方法を紹介します。

流れとしては

  1. MaterialをPOST
  2. レスポンスに含まれるProductのsampleImageUrlを使って画像を表示
  3. 購入に進む
    商品ページいくには、ProductのsampleUrlへ遷移する
  4. 修正に戻る
    MaterialをDeleteする。

画像を表示を行うためには、前述したようにProductからsampleImageUrlを取得する必要があります。そこで/api/v1/materialsへPOSTリクエストを行い、Productを作成します。

bodyのjsonの一例です。
textureに画像URL、データURIのいずれかを指定します。
productsに配列で、作りたいItemのIdと、オプションがあれば指定します。

{
  "texture": "https://old.yukyu.net/images/works/live-2d-model-yukyu/yukyu-v.png",
  "title": "yukyu",
  "price": 100,
  "description": "yukyuのグッズです",
  "products": [
    {
      "itemId": 1,
      "published": true
    }
  ]
}

POSTリクエストを行うと、レスポンスに作ったProductがあるのでsampleImageUrlでプレビューを表示できます。
もし、購入に進むのであればProductに含まれるsampleUrlへ遷移します。
修正にもどるや、購入しないなどの場合は、/api/v1/materials/{material_id}へDELETEリクエストを行うことで、MaterialやProductの情報を削除できます。

ItemIdが知りたい時にItem一覧を取得する

/api/v1/itemsをGETリクエストを行うと、現在取り扱っているItemの一覧が返ってきます。
これから作りたいItemの情報をとり、ItemIdを知ることができます。

2024/12/14時点でのレスポンスをgistで公開しておきます。

https://gist.github.com/yukyu30/54410bcf7060e11a6fef9737f05785d7

SUZURI APIを楽しんでほしい

SUZURI APIは、アプリケーションから有体物を作ることができる(購入すれば)とても楽しいものなので、ぜひたくさんの人に使って欲しいなと思っています。

今までにSUZURI APIでつくったもの

🎅GMOペパボ エンジニア Advent Calendar 2024の14日目でした！！！！
15日目は、ほみるんさんです！

Discussion