Intents API で Shopify 純正のファイルピッカーを開く

図解 ： Intents API で Shopify のファイルピッカーを開く Developer Changelog / 新 API Intents API で Shopify 純正のファイルピッカーを開く アプリが API 一発で「Shopify のファイルライブラリから選ぶ」画面を呼び出せるようになった。独自のファイル選択 UI を作る必要も、別画面に誘導する必要もなくなる。選択結果はファイル ID の配列で返ってくる。 このページの構成 そもそも何ができるようになったのか（30秒で理解） 仕組み図解 ： invoke から ID 取得までの流れ 最小コード例 この Intent の主なオプション 従来 vs Intents API の比較 使い始める3ステップ 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何ができるようになったのか アプリから pick:shopify/File という新しい Intent を呼ぶだけで、Shopify ネイティブのファイルピッカーが開けるようになった。 マーチャントは見慣れた Shopify のファイルライブラリからファイルを選び、アプリはその 選択結果をファイル ID の配列で受け取れる 。 従来 ： 自前でピッカーを作る 独自のファイル選択 UI を実装するか、マーチャントを別フローに飛ばす必要があった。実装コストも UX の分断も発生していた。 これから ： Shopify 純正を呼ぶだけ API 一発で Shopify のファイルピッカーが開く。メディア種別での絞り込み・複数選択・事前選択にも対応。結果は ID 配列で返る。 2 仕組み図解 ： invoke から ID 取得までの流れ Intents API とは ： アプリから Shopify 側のネイティブな操作（ここではファイル選択）を「意図（intent）」として呼び出す仕組み。 アプリは shopify.intents.invoke() で意図を投げ、返ってくる activity の complete を待つだけで結果を受け取れる。 3 最小コード例 const activity = await shopify.intents. invoke ( 'pick:shopify/File' ); const response = await activity.complete; if (response. code === 'ok' ) { console. log ( 'Selected file IDs:' , response. data . ids ); // response.data.ids は選択されたファイル ID の配列 } App Home（iframe）でも UI Extension でも同じ呼び出し方 で動く。 invoke でピッカーを開き、 activity.complete を await して、 response.code === 'ok' なら response.data.ids を受け取る、という3行が基本形。 4 この Intent の主なオプション メディア種別で絞り込み ファイルライブラリの中身を、必要なメディア種別だけに絞り込んで表示できる（オプション）。 複数選択を許可 複数選択を有効化できる。選ばれたファイルはまとめて ID の配列で返ってくる。 ファイルを事前選択 ピッカーを開いた時点で特定ファイルを選択済み状態にできる。編集・差し替えフローに便利。 結果はファイル ID の配列 選択完了時、 response.data.ids に選ばれたファイル ID が配列で入って返る。 絞り込みに使える具体的なメディア種別の値や、事前選択・複数選択を指定する引数の正確な書式は、本文には個別の記載なし。実装時は App Home / UI Extension の Intents ドキュメントで確認すること。 5 従来 vs Intents API の比較 項目 従来（自前ピッカー） Intents API（pick:shopify/File） ファイル選択 UI 自作 独自ピッカーを実装 純正 Shopify ネイティブを呼ぶだけ マーチャント体験 別フローへ誘導しがちで分断 見慣れたファイルライブラリで完結 呼び出し 独自の状態管理が必要 invoke → complete を await 絞り込み・複数選択・事前選択 すべて自前実装 オプション で指定可能 選択結果 自前で受け渡し設計 response.data.ids に配列で返る 6 使い始める3ステップ 1 Intent を invoke App Home か UI Extension から shopify.intents.invoke('pick:shopify/File') を呼ぶ。 2 complete を await 返ってきた activity の complete を待ち、マーチャントの選択完了を受け取る。 3 ids を受け取る response.code === 'ok' を確認し、 response.data.ids の配列を使う。 7 技術者が押さえるべき5つのポイント 1. 新 Intent は pick:shopify/File この文字列を invoke に渡すのが起点。Shopify のファイルライブラリを対象にしたファイル選択の意図を表す。 2. App Home でも UI Extension でも同じ App Home（iframe）と UI Extension の両方から、同一の呼び出し方で利用できる。コンテキストに合わせて使い分けられる。 3. activity.complete は Promise invoke は activity を返し、その complete を await して選択完了を待つ非同期フロー。UI をブロックしない設計にしやすい。 4. まず response.code を判定 結果を使う前に code === 'ok' を確認する。キャンセルや異常系の分岐をここで切る前提の API 形になっている。 5. 返るのは ID の配列（ファイル本体ではない） response.data.ids で受け取れるのは選択ファイルの ID 配列 。実際のファイル URL やメタデータが必要なら、その ID を使って Admin API 等で別途引く設計になる点に注意。 8 業務に活かせる3つのユースケース USE CASE 1 カスタムアプリの「画像差し替え UI」を純正ピッカーに置き換え 課題 商品ページや LP を編集する自社アプリで、画像選択のために独自のファイルアップロード／選択 UI を作り込んでおり、保守コストが高い。 打ち手 選択ボタンから pick:shopify/File を invoke し、Shopify のファイルライブラリをそのまま選択 UI として使う。返った ID をアプリ側で保持。 効果 自作ピッカーの実装・保守を削減。マーチャントは見慣れた画面で迷わず選べるため UX も安定。 技術メモ 絞り込みオプションで画像系に限定すれば誤選択を防げる。本文に値の記載は無いのでドキュメント要確認。 USE CASE 2 複数選択を活かした「素材まとめ取り込み」フロー 課題 ギャラリーやカタログ生成アプリで、1点ずつしか選べず、多数の画像を登録する作業が手間になっている。 打ち手 複数選択オプションを有効化してピッカーを開き、マーチャントにまとめて選んでもらう。 data.ids の配列をそのままバッチ処理に流す。 効果 素材登録の操作回数が激減。配列で受け取れるためアプリ側のループ処理にそのまま乗せられる。 技術メモ 返り値は ID 配列なので、後続で Admin API から各ファイルの URL・サイズ等を引く前提で設計する。 USE CASE 3 事前選択を使った「現在の設定を見せる」編集体験 課題 テーマ設定やバナー管理アプリで、今どのファイルが割り当てられているかが分かりにくく、誤って別ファイルを選ぶミスが起きる。 打ち手 事前選択オプションで現在割り当て中のファイルを選択済み状態にしてピッカーを開く。マーチャントは差分だけ操作すればよい。 効果 「今こうなっている」を起点に編集でき、取り違えミスを抑制。設定変更フローの納得感が上がる。 技術メモ 事前選択に渡す ID は、アプリが保持している現在値をそのまま流用する。指定書式はドキュメントで確認。 9 提案で使える1行サマリ 「 pick:shopify/File Intent を invoke するだけで、Shopify 純正のファイルピッカーを呼べる新 API。 自前ピッカーの実装ゼロ・メディア絞り込み／複数選択／事前選択に対応・結果はファイル ID 配列で返る。 App Home でも UI Extension でも同じ書き方でファイル選択を組み込める。」 source ： shopify.dev / changelog / intents-api-file-picker generated 2026-06-17