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

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

今回は [Salesforce APIs for Postman](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/overview) を利用して [GraphQL API](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-about.html) を利用する方法を紹介します。

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

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

* [Commerce Cloud](https://developer.salesforce.com/developer-centers/commerce-cloud)
* [Data Cloud](https://developer.salesforce.com/developer-centers/data-cloud)
* [Salesforce Platform](https://developer.salesforce.com/developer-centers#platform)
* [Marketing Cloud](https://developer.salesforce.com/developer-centers/marketing-cloud)
* [MuleSoft](https://developer.mulesoft.com/)
* [Tableau](https://www.tableau.com/developer)



## GraphQL API では何ができるの？

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

#### Resource aggregation

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

#### Schema introspection

クライアントはクエリの[スキーマを取得](https://graphql.org/learn/introspection/)できるためアプリケーション開発時の設計やテストに利用することができる。


## 制限 (2023/12/21 時点)

* [User Interface API をサポートしているオブジェクト](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_all_supported_objects.htm)のみクエリできます。
* サブクエリも 1 リクエストとして[レート制限](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/intro_rate_limits.htm)にカウントされます。
* 各サブクエリは 1 つのリクエストで最大 2000 レコードまで取得できます。それ以上クエリする場合はページネーションの [Upper-Bound](https://developer.salesforce.com/docs/platform/graphql/guide/paginate-use-upperbound.html)を利用できます。
* デフォルトでは最初の 10 レコードまでしか返ってこないので、[`first` プロパティ](https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html)や[ページネーション](https://developer.salesforce.com/docs/platform/graphql/guide/paginate.html)を利用しましょう。
* オブジェクトの作成・更新などの操作 (Mutation) は現時点ではベータバージョンです。



## Salesforce Postman Collection を利用する



#### 1. [Salesforce の Postman Collection](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/overview) からコレクションをフォークする

「Salesforce Platform APIs」というコレクションをフォークします。
![スクリーンショット 2023-12-25 12.28.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/58b15f0e-a79d-89bb-cbbf-e9d00fdfab04.png)



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

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

![スクリーンショット 2023-12-25 12.42.15.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/aa4f07da-2e42-0649-5244-12d3a644f3f7.png)



#### 3. Postman の変数の入力

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

![スクリーンショット 2023-12-25 15.01.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/f4fd275c-9733-12b8-e720-54d024136357.png)




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

コレクションの **[Authorization]** タブの **[Get New Access Token]** をクリックします。  
![スクリーンショット 2023-12-25 12.41.34.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/9de1656a-7764-397e-218d-88fe2c423bcd.png)

すると、OAuth の認可の画面が出てくるので **[許可]** をクリックします。
![スクリーンショット 2023-12-25 12.37.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/a522ff88-bd84-856f-72ea-b55e08deb147.png)


するとアクセストークンが画面に表示されるので **[Use Token]** をクリックします。
![スクリーンショット 2023-12-25 12.37.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/186ab6b4-be90-ed0f-bd5f-44abbefc6a4f.png)


#### 5. GraphQL API を呼ぶ

コレクションの「GraphQL」フォルダにサンプルのリクエストがあります。
**[Authorization]** タブで認証タイプが「Inherit auth from parent」になっていることを確認します。 
![スクリーンショット 2023-12-25 12.42.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/162a61a7-3e19-c06c-a388-0762fcea3e51.png)



あとは **[Send]** ボタンをクリックすればリクエストを実行できます。サンプルは取引先の ID と名前を取得するリクエストでした。
![スクリーンショット 2023-12-25 12.43.27.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/cf533063-41db-5d15-0879-edc784493fe8.png)


## 参考

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

https://github.com/forcedotcom/postman-salesforce-apis#installation

### ・ GraphQL Wire Adapter

GraphQL Wire Adapter は LWC を作成する際に利用できます。使い方は「[GraphQL Wire Adapter for LWC](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html)」をご覧ください。現状ちょっとした制限があるようなので下記に記載しておきます。

##### 制限 (2023/12/21 時点)

* エクスペリエンスクラウドのサイトでは利用できません。
* クエリを動的に変更することはできません。
* クエリないで Javascript の `${}` を利用して文字列の変数を扱うことはできません。
* Graphql の [directives](https://graphql.org/learn/queries/#directives) は利用できません。



### ・ Mutation（ベータ）について

Mutation ではオブジェクトの作成・更新などの操作が可能です。使い方は「[Mutations](https://developer.salesforce.com/docs/platform/graphql/guide/mutations-intro.html)」をご覧ください。こちらも現状ちょっとした制限があるようなので下記に記載しておきます。

##### 制限 (2023/12/21 時点)

* 子オブジェクトを作成することは現時点できません。
* [GraphQL wire adapter](https://developer.salesforce.com/docs/platform/graphql/guide/graphql-wire-lwc.html) は現状サポートされていません。