Figmaド素人のエンジニアがFigma APIを使ってみました | Offers Tech Blog

概要

こんにちは！
Offers を運営している株式会社 overflow の磯崎です。

弊社では、デザインツールとして Figma を使用しております。
デザインチームは Figma を使用してゴリゴリとデザイン作業を行っていくわけですが、こちらの Figma さんは API も充実しているので、ちょろっと開発すれば日々の業務の改善やモニタリング、他サービスへの通知など色々と作っていく事が可能です。

今回は、その Figma の API についてざーっとお伝えします。

この記事に書いてある情報は、2022/11/07 時点の情報であり、変更されている可能性もあります。
最新情報はドキュメントをご参照ください。
https://www.figma.com/developers

Figmaの各種用語について

私は未だに Figma の使い方がわかりません。
普段なんらかの開発タスク着手時に、デザインファイルとして閲覧はしますが、編集をすることはほとんどないです。
当然、用語もわからないので 1 つずつ理解していきました。

データ構造

Organization → Team → Project → File → Prototype

参考: https://help.figma.com/hc/ja/articles/1500007609322

Organization の中に複数 Team があり、
Team の中に複数 Project があり、
Project の中に複数 File が存在します。

File

Project 内に存在する各種ファイル

Comments

その名の通り、ファイル内に投稿されているコメント

Version history

Figma の右サイドバーに表示されているファイルバージョンです。

30 分誰も触らないと、新たな version が追加されるようです。

Figma saves your work by adding checkpoints to the file's version history. Figma records a new checkpoint after 30 minutes of inactivity in the file. If more than one person is editing a file, both contributors will need to be inactive for 30 minutes for Figma to create a version.

引用元: https://help.figma.com/hc/en-us/articles/360038006754-View-a-file-s-version-history

Projects

Team が保持するプロジェクト
プロジェクトの中にたくさんのファイルが存在する

Components

プロジェクト、ファイルをまたいで再利用できるパーツ

参考: https://help.figma.com/hc/ja/articles/360038662654-Figmaのコンポーネントについてのガイド

Style

色や、フォントサイズなどのスタイル
これを登録しておくことで、プロジェクトやファイルをまたいで再利用可能

Create styles for:
Paints and colors: fill, stroke, background color
Text: font family, size, line height, spacing
Effects: drop shadow, inner shadow, layer blur, background blur
Layout grids: row, column, grid
`

引用元: https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma

REST API でできること

上述した、File、Comments, Version history などの取得が可能です。
コメントだけ、取得に加えて投稿や削除もできます。

Webhook

βですが、Figma には Webhook もあります。
こちらは実際にページ上で設定できないため、API を叩いて Webhook の登録、確認、削除をする形となります。

現在、Professional Plan 以上でしか使用できません。
また、βなのでいつ破壊的変更が行われるかはわからず、動作もたまに不安定な時があります。

参考: https://www.figma.com/developers/api#webhooks_v2

認証

アクセストークンを発行するか、OAuth 認証で取得したトークンを用いてリクエストを行うのみです

参考: https://www.figma.com/developers/api#authentication

実際に叩いてみる

https://www.figma.com/developers/api#intro
Figma にログイン状態で、右のサイドバーの「Get personal access」を押してトークンを取得し、Submit するのみです。何か確認したい時はいつもここで実験してます。ドキュメントとセットで配置されており、非常に助かってます。

個人的に困ったこと

1. Fileで「誰」が編集したかを取得したい

File が編集された時に、その変更履歴のログを外部サービスから参照したいケースで発生しました。
やり方としては主に２つです。

• File 取得 API を定期で叩いてデータ取得。「最終編集者」と「最終編集日時」を最新のデータを取得
• Webhook の FILE_UPDATE イベントを受信

前者の API を叩く方法は、最終編集日時は取得できますが、最終編集者は取得できません。
Webhook の FILE_UPDATE イベントにも、「誰」が操作したかは response に含んでいません。

この生の編集ログを用いて色々できそうなので、いつかは「誰」が操作をしたかを含めてくれると嬉しいです。
別で、Activity Logs というエンタープライズプランご利用の方向けの API も最近出現したので、細かく取りたい場合はお金を支払いそちらを使ってねという意図もあるかもしれないです。

似たようなものとして、「誰」が「いつ」「なにを」編集したかを知る術としては、Version history も使用可能です。
しかし、その名の通りある地点での編集の区切りなので、ざっくりとした変更しか取得できません。
こちらは、「誰」が操作したかは、webhook, API 共に response に含まれています。

2. Webhook登録数上限に達した時に、削除試みるも、謎のエラーコードが返ってきて削除できない

こちら解決済みです。

なにをやっても削除できなかったので、サポートに問い合わせた所、真摯にご対応いただきましたが、結局原因はわからず、解決策も見つからずに 1 回は諦めました。
その後そういえばどうなっているんだろうと思い、数ヶ月経過後くらいに再度叩いてみたところうまく削除できたので、しれっと直して頂いたものなのかなと思いました。

3. Webhookが挙動不審で飛んでくる時とこない時がある

未だにパターン不明なのですが、イベントが飛んでこなくなるケースが有りました。

同イベントを複数エンドポイントに対して Webhook 登録した Team にて発生したので、そうなのかなと思いつつも、真相究明には至っていません。

たまーに飛んできたりするのですが、これは一体なんだろうと思いつつ、βなのであまり深追いせず、ゆるっとお付き合いをしております。

おわりに

Figma は素晴らしいサービスですね。今後開発者にとってももっとフレンドリーになっていただけると、色々と遊べるのでとても楽しみにしています。

今回は、Figma API のざっくり説明と個人的に困った点をシェアしましたが、もし Figma を操作する必要性に駆られたエンジニアの方々に少しでも参考になれば幸いです。

いつかこれを用いて、デザインチームの方々の業務効率化や可視化に貢献できればとても幸せですので、これからもデザインチーム、開発チーム、手を取り合って良いプロダクト作っていきましょう。