Salesforce APIs for Postman を利用して GraphQL API を利用してみる

※ これから記載する事項は、私が所属する会社とは一切関係のない事柄です。

今回は Salesforce APIs for Postman を利用して GraphQL API を利用する方法を紹介します。

Salesforce APIs for Postman では何ができるの？

現状下記の製品群の API が Postman で公開されているようです。これらを利用して開発時の参照として使ったり、実装の参考にすることができます。ただしオープンソースとして管理されており、SLA でカバーされるわけではないのでその点注意が必要です。

• Commerce Cloud
• Data Cloud
• Salesforce Platform
• Marketing Cloud
• MuleSoft
• Tableau

GraphQL API では何ができるの？

Field selection

アプリケーション作成時に必要な特定のオブジェクトのフィールドのみを絞ってクエリできるので、データ量の削減につながります。

Resource aggregation

クライアントから平均や合計といった集計情報を取得できるので、サーバー側での実装や不要なサーバーとのやりとりを無くします。

Schema introspection

クライアントはクエリのスキーマを取得できるためアプリケーション開発時の設計やテストに利用することができる。

制限 (2023/12/21 時点)

• User Interface API をサポートしているオブジェクトのみクエリできます。
• サブクエリも 1 リクエストとしてレート制限にカウントされます。
• 各サブクエリは 1 つのリクエストで最大 2000 レコードまで取得できます。それ以上クエリする場合はページネーションの Upper-Boundを利用できます。
• デフォルトでは最初の 10 レコードまでしか返ってこないので、first プロパティやページネーションを利用しましょう。
• オブジェクトの作成・更新などの操作 (Mutation) は現時点ではベータバージョンです。

Salesforce Postman Collection を利用する

1. Salesforce の Postman Collection からコレクションをフォークする

「Salesforce Platform APIs」というコレクションをフォークします。

2. 組織に接続アプリケーションを作成し、クライアント ID を取得する

接続したい組織に OAuth を行こうにした接続アプリケーションを作成します。その際 [コールバック URL] には https://oauth.pstmn.io/v1/browser-callback（Postman のブラウザの場合）と https://oauth.pstmn.io/v1/callback（Postman のデスクトップの場合）を入力してください。また、[選択した OAuth 範囲] には api を入れておきます。
作成が環境したら [コンシューマーの詳細を管理] からコンシューマー鍵 (クライアント ID) を取得します。

3. Postman の変数の入力

上記で作成したクライアント ID をコレクションの [Variables] タブの clientId に入力します。また同時に API を呼ぶ際の URL を _endpoint に入力します（URL がわからない場合は後のアクセストークン取得時に表示されるので後でも構いません。）。
入力したら必ず保存してください。

4. アクセストークンを取得する

コレクションの [Authorization] タブの [Get New Access Token] をクリックします。

すると、OAuth の認可の画面が出てくるので [許可] をクリックします。

するとアクセストークンが画面に表示されるので [Use Token] をクリックします。

5. GraphQL API を呼ぶ

コレクションの「GraphQL」フォルダにサンプルのリクエストがあります。
[Authorization] タブで認証タイプが「Inherit auth from parent」になっていることを確認します。

あとは [Send] ボタンをクリックすればリクエストを実行できます。サンプルは取引先の ID と名前を取得するリクエストでした。

参考

・ Salesforce APIs for Postman の Github レポジトリ

・ GraphQL Wire Adapter

GraphQL Wire Adapter は LWC を作成する際に利用できます。使い方は「GraphQL Wire Adapter for LWC」をご覧ください。現状ちょっとした制限があるようなので下記に記載しておきます。

制限 (2023/12/21 時点)

• エクスペリエンスクラウドのサイトでは利用できません。
• クエリを動的に変更することはできません。
• クエリないで Javascript の ${} を利用して文字列の変数を扱うことはできません。
• Graphql の directives は利用できません。

・ Mutation（ベータ）について

Mutation ではオブジェクトの作成・更新などの操作が可能です。使い方は「Mutations」をご覧ください。こちらも現状ちょっとした制限があるようなので下記に記載しておきます。

制限 (2023/12/21 時点)

• 子オブジェクトを作成することは現時点できません。
• GraphQL wire adapter は現状サポートされていません。