<p data-line="0" class="code-line"><a href="https://adventar.org/calendars/10036" target="_blank" rel="nofollow noopener noreferrer">🎅GMOペパボ エンジニア Advent Calendar 2024</a>の14日目です。</p>
<p data-line="2" class="code-line">13日目は<a href="https://yana-g.hatenablog.com/entry/2024/12/13/230627" target="_blank" rel="nofollow noopener noreferrer">OCRとLeafletでイベント会場の目的地が一目で分かるマップを作った</a>でした。即売会やイベントでクリエイターさんのブースをパンフレットから探すのは大変なので、フォローしているアカウントを元に、自動でマップにピンが立つのはとても便利でした〜!</p>
<p data-line="4" class="code-line">この記事では、SUZURI APIを用いたアプリケーションを作る時に細かなTipsを書いていきます。</p>
<h2 id="suzuri%E3%81%A8suzuri-api%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6" data-line="7" class="code-line">
<a class="header-anchor-link" href="#suzuri%E3%81%A8suzuri-api%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6" aria-hidden="true"></a> SUZURIとSUZURI APIについて</h2>
<p data-line="8" class="code-line">SUZURI APIの前にSUZURIを知らない方向けに大まかなサービス内容を紹介します。</p>
<p data-line="10" class="code-line"><a href="https://lp.suzuri.jp/hello_creators?_gl=1*1v3pkjm*_gcl_aw*R0NMLjE3MzA3OTAzOTkuQ2owS0NRaUEyWkNPQmhEaUFSSXNBTVJmdjlLTFRIZjhSQk0wYi1qRFBBT0Fxb1NRUk9DdEdubzc1clV6LWZNaHhqbXQ1aUVMNF83VEpTY2FBaFdRRUFMd193Y0I.*_gcl_au*NjA4NTEyODQwLjE3MjcyNTcxMjE.*_ga*MTE5OTg3MDI3NS4xNzExNjkxOTQz*_ga_K4RMMPG20T*MTczNDE0MzQzMi4yMjIuMS4xNzM0MTQzNDkxLjEuMC4w" target="_blank" rel="nofollow noopener noreferrer">SUZURI</a>はグッズ作成・販売、デジタルコンテンツ販売、コミッションを行えるサービスです。<br>
グッズ作成・販売では、受注生産のため1点からのグッズ販売ができます。</p>
<p data-line="13" class="code-line">SUZURI APIはSUZURIの一部の機能を外部のアプリケーションから利用できるものです。<br>
できることしては、</p>
<ul data-line="16" class="code-line">
<li data-line="16" class="code-line">グッズの作成、削除</li>
<li data-line="17" class="code-line">グッズの検索</li>
<li data-line="18" class="code-line">ズッキュン(お気に入り)の登録と削除</li>
</ul>
<p data-line="20" class="code-line">などです。</p>
<p data-line="22" class="code-line">利用料金はなく、SUZURIユーザーであれば誰でもお使いいただけます。</p>
<aside class="msg message"><span class="msg-symbol">!</span><div class="msg-content">
<p data-line="25" class="code-line">これ以降、SUZURI APIを使ったアプリケーションを利用するユーザーを「アプリユーザー」といいます。</p>
</div></aside>
<h3 id="suzuri-api%E3%81%AB%E5%88%A9%E7%94%A8%E6%96%B9%E6%B3%95%E3%81%A8%E5%B7%AE%E7%95%B0" data-line="28" class="code-line">
<a class="header-anchor-link" href="#suzuri-api%E3%81%AB%E5%88%A9%E7%94%A8%E6%96%B9%E6%B3%95%E3%81%A8%E5%B7%AE%E7%95%B0" aria-hidden="true"></a> SUZURI APIに利用方法と差異</h3>
<p data-line="30" class="code-line">SUZURI APIは二つの方法で利用できます。</p>
<ol data-line="31" class="code-line">
<li data-line="31" class="code-line">アプリケーションで1つのToken を使って、APIを利用</li>
<li data-line="32" class="code-line">OAuthを使って、APIを利用<br>
<a href="https://suzuri.jp/developer/documentation/v1#auth" target="_blank" rel="nofollow noopener noreferrer">https://suzuri.jp/developer/documentation/v1#auth</a>
</li>
</ol>
<p data-line="35" class="code-line">今回はSUZURI APIではOAuth認証を利用しました。利用方法による主な違いは以下の通りです。</p>
<table data-line="36" class="code-line">
<thead data-line="36" class="code-line">
<tr data-line="36" class="code-line">
<th></th>
<th>1.Tokenを使ったAPI利用</th>
<th>2.OAuthを使ったAPI利用</th>
</tr>
</thead>
<tbody data-line="38" class="code-line">
<tr data-line="38" class="code-line">
<td>グッズ作成時の販売ショップ</td>
<td>Tokenを発行したユーザー(=アプリケーションの運営者)のショップ</td>
<td>利用ユーザーにショップ</td>
</tr>
<tr data-line="39" class="code-line">
<td>取得できる商品情報</td>
<td>公開されたグッズ + Tokenを発行したユーザー(=アプリケーションの運営者)の非公開グッズ</td>
<td>公開されたグッズ + アプリユーザーの非公開グッズ</td>
</tr>
</tbody>
</table>
<p data-line="41" class="code-line">どちら方法で利用するかは、以下に2ポイントで決めています</p>
<ul data-line="42" class="code-line">
<li data-line="42" class="code-line">トリブンのもらう人が誰か</li>
<li data-line="43" class="code-line">アプリユーザーの非公開グッズを取得したいか</li>
</ul>
<p data-line="46" class="code-line">具体的にどんなふうに選んでいるかご紹介します。<br style="display:none">
<span class="embed-block zenn-embedded zenn-embedded-tweet"><iframe id="zenn-embedded__e11c253b2c60d" src="https://embed.zenn.studio/tweet#zenn-embedded__e11c253b2c60d" data-content="https%3A%2F%2Fx.com%2Fyukyu30%2Fstatus%2F1859264148657578337" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://x.com/yukyu30/status/1859264148657578337" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://x.com/yukyu30/status/1859264148657578337</a><br style="display:none">
以上のようなPR画像生成ツールを作った時には、OAuthを使ったAPI利用を採用しました。理由としては以下の通りです。</p>
<ul data-line="49" class="code-line">
<li data-line="49" class="code-line">グッズを作成しないのでトリブンが発生しない</li>
<li data-line="50" class="code-line">セールに合わせてグッズを公開するというアプリユーザがいるため、非公開グッズを取得したい</li>
</ul>
<p data-line="52" class="code-line">OAuthを使ったAPI利用では、アプリケーションの登録が必要です。登録を行うと、<br>
<code>OAuth Client id</code>と<code>OAuth Client Secret</code>が発行されます。<br>
<img src="https://storage.googleapis.com/zenn-user-upload/54c11b23ea76-20241214.png" loading="lazy" class="md-img"></p>
<p data-line="56" class="code-line">Callback URLは、httpsである必要があるため、自分はOrbstackなどのツールを使って、Local環境にhttpsでアクセスできるようにしています。</p>
<p data-line="58" class="code-line">次の章からは実際にSUZURI APIを使うときのTipsを紹介します。</p>
<h3 id="%E3%82%B0%E3%83%83%E3%82%BA%E7%94%BB%E5%83%8F%E3%81%AE%E5%8F%96%E5%BE%97%E7%9B%AE%E7%9A%84%E3%81%A7%E3%81%AF%E3%80%81sampleimageurl%E3%81%8C%E4%BD%BF%E3%81%84%E3%82%84%E3%81%99%E3%81%84" data-line="60" class="code-line">
<a class="header-anchor-link" href="#%E3%82%B0%E3%83%83%E3%82%BA%E7%94%BB%E5%83%8F%E3%81%AE%E5%8F%96%E5%BE%97%E7%9B%AE%E7%9A%84%E3%81%A7%E3%81%AF%E3%80%81sampleimageurl%E3%81%8C%E4%BD%BF%E3%81%84%E3%82%84%E3%81%99%E3%81%84" aria-hidden="true"></a> グッズ画像の取得目的では、<code>sampleImageUrl</code>が使いやすい</h3>
<p data-line="61" class="code-line">グッズの画像を表示する時には、APIのレスポンスに含まれる、Productの<code>sampleImageUrl</code>、<code>pngSampleImageUrl</code>を、imgタグのsrcに指定しするのが一番簡単です。</p>
<p data-line="63" class="code-line"><code>sampleImageUrl</code>ではwebp画像で、<code>pngSampleImageUrl</code>ではpng画像が取得できます。</p>
<p data-line="65" class="code-line"><code>imageUrl</code>などでは、各パラメータを自分たちで置き換える必要があるため、size指定や色指定などのこだわりがある時に使います。<br>
<img src="https://storage.googleapis.com/zenn-user-upload/a000c9beee54-20241214.png" loading="lazy" class="md-img"></p>
<h3 id="%E5%95%86%E5%93%81%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%B8%E3%81%AE%E9%81%B7%E7%A7%BB%E3%81%AB%E3%81%AFsampleurl%E3%81%8C%E4%BD%BF%E3%81%84%E3%82%84%E3%81%99%E3%81%84" data-line="68" class="code-line">
<a class="header-anchor-link" href="#%E5%95%86%E5%93%81%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%B8%E3%81%AE%E9%81%B7%E7%A7%BB%E3%81%AB%E3%81%AFsampleurl%E3%81%8C%E4%BD%BF%E3%81%84%E3%82%84%E3%81%99%E3%81%84" aria-hidden="true"></a> 商品ページへの遷移には<code>sampleUrl</code>が使いやすい</h3>
<p data-line="69" class="code-line">グッズの詳細ページに遷移するには、Productに含まれる<code>sampleUrl</code>が一番簡単です。<br>
クリック時の遷移先にsampleUrlを指定すると、SUZURIのグッズ詳細ページに遷移できます。</p>
<p data-line="72" class="code-line">次は、これらを組み合わせた実践的な内容を紹介します。</p>
<h3 id="%E7%94%BB%E5%83%8F%E3%82%92%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%97%E3%81%A6%E3%80%81%E3%82%B0%E3%83%83%E3%82%BA%E3%81%AE%E3%83%97%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%97%E3%81%9F%E3%81%84%E3%81%A8%E3%81%8D%E3%81%AB%E3%82%82product%E3%82%92%E4%B8%80%E5%9B%9E%E4%BD%9C%E3%82%8B" data-line="74" class="code-line">
<a class="header-anchor-link" href="#%E7%94%BB%E5%83%8F%E3%82%92%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%97%E3%81%A6%E3%80%81%E3%82%B0%E3%83%83%E3%82%BA%E3%81%AE%E3%83%97%E3%83%AC%E3%83%93%E3%83%A5%E3%83%BC%E3%81%97%E3%81%9F%E3%81%84%E3%81%A8%E3%81%8D%E3%81%AB%E3%82%82product%E3%82%92%E4%B8%80%E5%9B%9E%E4%BD%9C%E3%82%8B" aria-hidden="true"></a> 画像をアップロードして、グッズのプレビューしたいときにもProductを一回作る</h3>
<p data-line="75" class="code-line">ユースケースとしてよくある画像アップロードして、プレビューして購入を決めるというフローをSUZURI APIで実現する方法を紹介します。</p>
<p data-line="77" class="code-line">流れとしては</p>
<ol data-line="78" class="code-line">
<li data-line="78" class="code-line">MaterialをPOST</li>
<li data-line="79" class="code-line">レスポンスに含まれるProductのsampleImageUrlを使って画像を表示</li>
<li data-line="80" class="code-line">購入に進む<br>
商品ページいくには、ProductのsampleUrlへ遷移する</li>
<li data-line="82" class="code-line">修正に戻る<br>
MaterialをDeleteする。</li>
</ol>
<p data-line="86" class="code-line">画像を表示を行うためには、前述したようにProductからsampleImageUrlを取得する必要があります。そこで<code>/api/v1/materials</code>へPOSTリクエストを行い、Productを作成します。</p>
<p data-line="88" class="code-line">bodyのjsonの一例です。<br>
textureに画像URL、データURIのいずれかを指定します。<br>
productsに配列で、作りたいItemのIdと、オプションがあれば指定します。</p>
<div class="code-block-container"><pre><code class="code-line" data-line="91">{
  "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
    }
  ]
}
</code></pre></div><p data-line="107" class="code-line">POSTリクエストを行うと、レスポンスに作ったProductがあるのでsampleImageUrlでプレビューを表示できます。<br>
もし、購入に進むのであればProductに含まれるsampleUrlへ遷移します。<br>
修正にもどるや、購入しないなどの場合は、<code>/api/v1/materials/{material_id}</code>へDELETEリクエストを行うことで、MaterialやProductの情報を削除できます。</p>
<h3 id="itemid%E3%81%8C%E7%9F%A5%E3%82%8A%E3%81%9F%E3%81%84%E6%99%82%E3%81%ABitem%E4%B8%80%E8%A6%A7%E3%82%92%E5%8F%96%E5%BE%97%E3%81%99%E3%82%8B" data-line="111" class="code-line">
<a class="header-anchor-link" href="#itemid%E3%81%8C%E7%9F%A5%E3%82%8A%E3%81%9F%E3%81%84%E6%99%82%E3%81%ABitem%E4%B8%80%E8%A6%A7%E3%82%92%E5%8F%96%E5%BE%97%E3%81%99%E3%82%8B" aria-hidden="true"></a> ItemIdが知りたい時にItem一覧を取得する</h3>
<p data-line="113" class="code-line"><code>/api/v1/items</code>をGETリクエストを行うと、現在取り扱っているItemの一覧が返ってきます。<br>
これから作りたいItemの情報をとり、ItemIdを知ることができます。</p>
<p data-line="116" class="code-line">2024/12/14時点でのレスポンスをgistで公開しておきます。</p>
<p data-line="118" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__d92256e3cfc52" src="https://embed.zenn.studio/card#zenn-embedded__d92256e3cfc52" data-content="https%3A%2F%2Fgist.github.com%2Fyukyu30%2F54410bcf7060e11a6fef9737f05785d7" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://gist.github.com/yukyu30/54410bcf7060e11a6fef9737f05785d7" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://gist.github.com/yukyu30/54410bcf7060e11a6fef9737f05785d7</a></p>
<h3 id="suzuri-api%E3%82%92%E6%A5%BD%E3%81%97%E3%82%93%E3%81%A7%E3%81%BB%E3%81%97%E3%81%84" data-line="120" class="code-line">
<a class="header-anchor-link" href="#suzuri-api%E3%82%92%E6%A5%BD%E3%81%97%E3%82%93%E3%81%A7%E3%81%BB%E3%81%97%E3%81%84" aria-hidden="true"></a> SUZURI APIを楽しんでほしい</h3>
<p data-line="121" class="code-line">SUZURI APIは、アプリケーションから有体物を作ることができる(購入すれば)とても楽しいものなので、ぜひたくさんの人に使って欲しいなと思っています。</p>
<h3 id="%E4%BB%8A%E3%81%BE%E3%81%A7%E3%81%ABsuzuri-api%E3%81%A7%E3%81%A4%E3%81%8F%E3%81%A3%E3%81%9F%E3%82%82%E3%81%AE" data-line="123" class="code-line">
<a class="header-anchor-link" href="#%E4%BB%8A%E3%81%BE%E3%81%A7%E3%81%ABsuzuri-api%E3%81%A7%E3%81%A4%E3%81%8F%E3%81%A3%E3%81%9F%E3%82%82%E3%81%AE" aria-hidden="true"></a> 今までにSUZURI APIでつくったもの</h3>
<ul data-line="124" class="code-line">
<li data-line="124" class="code-line">クリエイターサポートツール(PR画像生成ツール) : <a href="https://zenn.dev/yu_9/articles/5fa3a6c9332afd" target="_blank">https://zenn.dev/yu_9/articles/5fa3a6c9332afd</a>
</li>
<li data-line="125" class="code-line">BECCHU(別注システム) : <a href="https://zenn.dev/yu_9/articles/yu9-becchu-2021" target="_blank">https://zenn.dev/yu_9/articles/yu9-becchu-2021</a>
</li>
<li data-line="126" class="code-line">ワクワクおえかきランド(新卒研修で作成したTシャツが作れるドット絵エディタ) : <a href="https://tech.pepabo.com/2022/07/14/12th-training-frontend/" target="_blank" rel="nofollow noopener noreferrer">https://tech.pepabo.com/2022/07/14/12th-training-frontend/</a>
</li>
<li data-line="127" class="code-line">LINEでTシャツを作成するbot : <a href="https://zenn.dev/articles/2022-12-31-line-data-convert" target="_blank">https://zenn.dev/articles/2022-12-31-line-data-convert</a>
</li>
<li data-line="128" class="code-line">LLMを使ってチャット形式でTシャツをつくる : <a href="https://www.youtube.com/watch?v=mIQXjPEEStA" target="_blank" rel="nofollow noopener noreferrer">https://www.youtube.com/watch?v=mIQXjPEEStA</a>
</li>
<li data-line="129" class="code-line">スリスリAIチャット(グッズ検索、雑談ができるチャットシステム) : <a href="https://tech.pepabo.com/2023/09/15/introducing-surisuri-ai-chat/" target="_blank" rel="nofollow noopener noreferrer">https://tech.pepabo.com/2023/09/15/introducing-surisuri-ai-chat/</a>
</li>
<li data-line="130" class="code-line">hakuran(引用をTシャツにするアプリ) : <a href="https://zenn.dev/yu_9/articles/5c30a7401ca62c" target="_blank">https://zenn.dev/yu_9/articles/5c30a7401ca62c</a>
</li>
<li data-line="131" class="code-line">プロフィールスマホストラップジェネレーター(s-toolの一部) : <a href="https://s-tool.yukyu.net/" target="_blank" rel="nofollow noopener noreferrer">https://s-tool.yukyu.net/</a>
</li>
<li data-line="132" class="code-line">PR画像生成ツール(s-toolの一部) : <a href="https://s-tool.yukyu.net/" target="_blank" rel="nofollow noopener noreferrer">https://s-tool.yukyu.net/</a>
</li>
</ul>
<p data-line="134" class="code-line"><a href="https://adventar.org/calendars/10036" target="_blank" rel="nofollow noopener noreferrer">🎅GMOペパボ エンジニア Advent Calendar 2024</a>の14日目でした！！！！<br>
15日目は、ほみるんさんです！</p>


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

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

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

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

Discussion