前回のブログでは、新しいSalesforce GraphQL APIの概要や、従来のREST APIと比較した場合のGraphQLの強みについてご紹介しました。今回はGraphQL APIの詳細や仕組み、Summer ’22のリリースで提供される機能について確認します。
Salesforce Platform向けGraphQL
Salesforce GraphQL APIはベータ版として、Summer ’22でリリースされます。APIを呼び出すには、{{urlBase}}/services/data/{{version}}/graphqlエンドポイントにPOSTリクエストを作成します。リクエストのサンプルはPostman Collectionをご覧ください。
スキーマーの構造
GraphQLエンドポイントは必ずスキーマに関連付けられます。スキーマとは、クライアントがGraphQL APIからリクエストできるリソースを示すものです。従来のREST APIでは、1つ1つのAPIが特定のエンドポイントに関連付けられます（たとえば、{{urlBase}}/services/data/{{version}}/ui-api/object-infoはObjectInfo APIのエンドポイントです）。一方、GraphQLの場合、エンドポイントは型と項目から構成されるスキーマに関連付けられます。このような項目には、REST APIと概念上類似していると考えられるものもあります。たとえば、GraphQLのリクエストではRESTエンドポイントの呼び出しと同様、「objectInfo」項目を要求すると、「ObjectInfo」の型が返されます。
このように、情報を得たい項目を宣言し、そのデータのみを返してもらうプロセスを「項目選択」と言います。GraphQLはエンドポイントの呼び出しではなく、項目選択を使ってリソースにアクセスしているため、さまざまなパラメーターで何度もobjectInfo項目を要求することができます。このため、複数のREST APIの呼び出しに代わって、単一のGraphQLリクエストを使うことができるのです。
多くの型や項目が持つ複雑さに対処するため、GraphQLスキーマはルートでいくつかの最上位型に分割されています。GraphQLスキーマはQuery型でデータを読み込み、Mutation型でデータを更新します。現在、このスキーマは読み込み専用で、SalesforceスキーマではQuery型のみ存在します。将来的には複数のAPIファミリーで構成される予定ですが、現時点でこのスキーマのAPIファミリーはUI APIのみです。APIファミリーは、Query型の中にそれぞれ最上位項目があり、APIファミリーと名前が同じです。たとえば、UI APIには「UIAPI」型の項目「uiapi」があります。これはスキーマのUI APIサブセットへのエントリポイントになります。
GraphQLを使ったレコードのクエリ
UI API型には、型「RecordQuery」の項目「query」があります。RecordQuery型には、それぞれのUI API対応オブジェクトのための項目が1つあります。このオブジェクトについて、ユーザは現在オブジェクトレベルのセキュリティ（OLS）の可視化が可能です（カスタムオブジェクトを含む）。スキーマには、現在のユーザのField Level Security（FLS）設定を考慮したsObjectsの具体的な表現が含まれます。
RecordQuery型を使うと、ページネーション、フィルター、順序づけが可能なsObjectsに対するクエリを作成できます。以下はAccountsに対する簡単なクエリの例です。
これに対し、以下のような回答が返されます。
ページネーション
多数の結果を処理する場合には、一度に受け取るのはこれらの結果のサブセットのみとすることが重要です。回答を通じてページネーションを行うには、引数のfirstとafterを使用します。ページネーションの構造は、標準の接続仕様に従います。
フィルタリング
回答をフィルターするには、引数whereを使用します。それぞれのsObject型に対応するフィルター型が作成されます。これを引数whereの型として使用します。たとえば、「Account」型は「Account_Filter」型に対応します。フィルター型は「and」、「or」、「not」の項目と組み合わせることができます。これらはブール演算子に対応します。
項目型内のsObject上の各項目には、対応する演算子の型があります。これにより、等価性や順序づけなどによるフィルタリングが可能になります。
以下の例では「Entertainment」に類似する特定のIdおよびNameでAccountを検索しています。
順序づけ
回答の順序を付けるには、引数orderByを使用します。それぞれのsObject型に対応するOrderBy型が作成されます。これを引数orderByの型として使用します。これまでと同様、「Account」には一致する「Account_OrderBy」の型があります。
OrderBy型内のsObject上の各項目は「OrderByClause」の型となります。これは、この項目上の順序を考慮しています。以下は、NameによりAccountsの順序づけをした例です。
もちろん、上記の引数をさまざまな方法で組み合わせて、希望するクエリを作成することができます。その他のリクエストのサンプルはPostman Collectionをご覧ください。
GraphiQLとSalesforceの接続
GraphiQLは、GraphQL Foundationが作成および管理するGraphQLの統合開発環境（IDE）です。これを使ってGraphQLサーバーに対するクエリを実行したり、スキーマ文書を検索したりすることができます。GraphQL APIとのやり取りにおいて、最も有用なツールの1つです。
GraphiQLを活用する場合は、GraphiQL Onlineを利用するのが最も簡単ですが、デスクトップバージョン（MacOS、Linuxのみに対応）をダウンロードしたり、ユーザ自身が実行およびホスティングしたりすることも可能です。
APIをクエリするには、以下の2つが必要です。
- GraphQL APIエンドポイント
- APIアクセストークン
APIアクセストークンを取得する方法は、Salesforce API RESTドキュメントを参照し、クイックスタートガイドに従ってConnected Appを作成した後、OAuthで認証の設定を実施してください。
デモとしてはクイックスタートガイドのcurlのアプローチをご利用いただけますが、本番環境のアプリケーションでは、ユースケースにあったOAuth認証フローを利用することをお勧めします。
GraphiQLでSalesforce GraphQL APIエンドポイントに接続し、以下のHTTPリクエストヘッダーが設定されていることを確認します。
- Content-Type：application/json
- Authorization：Bearer <アクセストークン>
- X-Chatter-Entity-Encoding：false
次に例を示します。
これでGraphQLインスタンスにサンプルのクエリを送信できるようになりました。次に、以下のクエリを試してみましょう。Playボタンをクリックして実行し、結果を取得します。
右側のパネルのような結果になるはずです。GraphiQL Onlineでは、左側に便利なExplorerパネルが表示されています。これを使って、クエリしている型で利用できるさまざまな項目やパラメーターを確認できます。
また、右側のDocsメニューをクリックすると、GraphQLスキーマ文書を確認することもできます。クリックすると、Salesforce GraphQLスキーマで利用できるさまざまな型やクエリがすべて表示されたパネルが開きます。
Salesforce GraphQLのロードマップの定義
Salesforce GraphQLスキーマは、まずUI APIが公開されたsObjectのページネーション、フィルター、順序づけの機能を提供します。将来的には、Object InfoやRecord LayoutなどのUI APIファミリーの追加リソースや、その他のSalesforce APIファミリーのリソースを追加したいと考えています。スキーマに追加してほしいリソースがあれば、IdeaExchangeでお知らせください。GraphQL APIへのご意見がある方は、GraphQL IdeaExchangeの投稿にコメントをお寄せください。
著者紹介
Spencer MacKinnonは開発者として、GraphQLの開発に精力的に取り組んでいます。これまでさまざまな趣味を楽しんできましたが、現在は生後10週の子犬、Meropeを毎晩のように追いかけています。
Ben Sklarはシニア製品マネージャーで、GraphQLの熱心な支持者です。趣味はスキーですが、ほとんどの時間をキャバプーのPercyと過ごしています。
Julián DuqueはSalesforceのプリンシパルディベロッパーアドボケートです。開発者であると同時に教育者でもある彼の趣味は、オンラインゲーム「Dungeons & Dragons」や、ミニチュアオーストラリアンシェパードのCumbiaと遊んだりトレーニングしたりすることです。