Salesforce GraphQL API: 効率的なデータ統合と取得のためのガイド

Salesforce統合エンジニアとして、日々様々なシステム間のデータ連携を担当しています。従来の連携方法、特にREST APIには、長年にわたりお世話になってきましたが、同時にいくつかの課題も感じていました。本日は、これらの課題を解決する強力な選択肢として登場したSalesforce GraphQL APIについて、統合エンジニアの視点から解説します。

背景と適用シナリオ

システム統合の現場では、クライアント（例えば、モバイルアプリやウェブフロントエンド）が必要とするデータを、サーバー（Salesforce）から効率的に取得することが常に求められます。従来のREST APIアプローチでは、しばしば以下のような課題に直面します。

Over-fetching (過剰なデータ取得)

REST APIのエンドポイントは、通常、特定のオブジェクトに対して定義された固定のデータセットを返します。例えば、取引先責任者の情報を取得するエンドポイントは、常に氏名、役職、電話番号、メールアドレスなど、全ての標準フィールドを返すかもしれません。しかし、クライアント側が「氏名」と「メールアドレス」しか必要としない場合、不要なデータまで取得することになり、ネットワーク帯域の無駄遣いや、クライアント側のパフォーマンス低下につながります。これをOver-fetchingと呼びます。

Under-fetching (データ不足)とN+1問題

逆に、1つの画面に複数の関連オブジェクトの情報を表示したい場合、REST APIでは複数のリクエストが必要になることがあります。例えば、「特定の取引先情報」と、その取引先に紐づく「全ての取引先責任者の名前リスト」、さらに「直近の商談5件のフェーズ」を表示したいとします。この場合、

取引先取得APIをコール
取引先IDを使って、取引先責任者取得APIをコール
取引先IDを使って、商談取得APIをコール

といった具合に、最低でも3回のAPIコールが必要になります。これはUnder-fetchingと呼ばれ、リクエスト回数の増加はレイテンシーの悪化に直結します。特に、リストの各項目に対して関連情報を取得するようなケースでは、リクエスト数が爆発的に増える「N+1問題」を引き起こす原因となります。

これらの課題を解決するために、Facebook（現Meta）によって開発され、オープンソース化されたのがGraphQL (APIのためのクエリ言語)です。Salesforceもこの技術をプラットフォームに導入しました。GraphQL APIを利用することで、クライアントは「必要なデータだけを」「1回のリクエストで」構造化して取得できるようになり、統合の効率性とパフォーマンスを劇的に向上させることが可能です。

原理の説明

GraphQLは、RESTとは根本的に異なるアプローチを取ります。RESTが「リソース」の概念に基づき、各リソース（例: `/services/data/vXX.X/sobjects/Account/{accountId}`）に対して個別のエンドポイントを用意するのに対し、GraphQLは通常、単一のエンドポイント（Salesforceでは `/services/data/vXX.X/graphql`）に対して「クエリ」を送信します。

Schema (スキーマ)

GraphQL APIの中心的な概念はSchema (スキーマ)です。スキーマは、APIで利用可能なデータの型、クエリ、リレーションシップを厳密に定義したものです。これはクライアントとサーバー間の「契約書」のような役割を果たし、どのようなデータが取得可能か、どのような形式でリクエストすべきかを明確にします。クライアントは、このスキーマを事前に知ることで、有効なクエリを構築できます。このスキーマの存在により、APIは自己文書化されるというメリットもあります。

Query (クエリ)

データの読み取りを行うための操作です。クライアントはJSONによく似た構文で、取得したいオブジェクト、フィールド、そしてオブジェクト間のリレーションを記述したクエリをサーバーに送信します。サーバーはクエリを解析し、その構造通りにデータを整形してJSON形式で返します。これにより、前述のOver-fetchingやUnder-fetchingの問題が解決されます。

Mutation (ミューテーション)

データの作成、更新、削除といった書き込み操作を行うためのものです。Queryが読み取り専用であるのに対し、Mutation (ミューテーション)はデータの状態を変更する際に使用します。

SalesforceのGraphQL APIは、`uiapi`というルートフィールドを通じて標準およびカスタムオブジェクトへのアクセスを提供します。これにより、SOQLクエリのように柔軟なデータ取得が可能になりますが、その構文はより階層的で、クライアントアプリケーションのデータ構造と親和性が高いのが特徴です。

示例代码

ここでは、特定の条件に一致する取引先（Account）と、それに関連する取引先責任者（Contact）の情報を1回のリクエストで取得するGraphQLクエリの例を示します。これはまさに、Under-fetchingを解決するGraphQLの典型的なユースケースです。

GraphQL クエリの例

以下のクエリは、「BillingState」が「CA」である取引先の「Name」と「AnnualRevenue」、そしてその取引先に紐づく全ての取引先責任者の「FirstName」と「LastName」を取得します。

query accountWithContacts {
  uiapi {
    query {
      Account(where: { BillingState: { eq: "CA" } }, first: 5) {
        edges {
          node {
            Name {
              value
            }
            AnnualRevenue {
              displayValue
            }
            Contacts {
              edges {
                node {
                  FirstName {
                    value
                  }
                  LastName {
                    value
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

コードの解説:

query accountWithContacts: クエリに名前を付けています（任意ですが推奨されます）。
uiapi: Salesforceのオブジェクトデータにアクセスするためのルートフィールドです。
Account(...): クエリの対象となるsObjectを指定します。
where: { BillingState: { eq: "CA" } }: SOQLのWHERE句に相当し、レコードをフィルタリングします。「BillingState」が「CA」のレコードに絞り込んでいます。
first: 5: 取得するレコード数を5件に制限します。
edges/node: GraphQLのカーソルベースのページネーションの標準的な構文です。`node`が実際のレコードデータを格納します。
Name, AnnualRevenue: 取引先オブジェクトから取得したいフィールドを指定します。`value`で実際の値、`displayValue`でフォーマットされた表示値を取得できます。
Contacts { ... }: ここがGraphQLの強力な点です。取引先オブジェクトの内部で、関連する`Contacts`（リレーション名）をネストしてクエリしています。これにより、関連オブジェクトのデータを一度に取得できます。

cURL を使ったリクエストの実行

このクエリをSalesforceのエンドポイントに送信するには、cURLなどのHTTPクライアントを使用します。リクエストボディにGraphQLクエリを格納します。

curl -X POST \
-H "Authorization: Bearer [YOUR_SESSION_ID]" \
-H "Content-Type: application/json" \
-d '{ "query": "query accountWithContacts { uiapi { query { Account(where: { BillingState: { eq: \"CA\" } }, first: 5) { edges { node { Name { value } AnnualRevenue { displayValue } Contacts { edges { node { FirstName { value } LastName { value } } } } } } } } } }" }' \
https://[YOUR_INSTANCE].my.salesforce.com/services/data/v58.0/graphql

注意: `[YOUR_SESSION_ID]`と`[YOUR_INSTANCE]`は、ご自身の環境の値に置き換えてください。

期待されるレスポンス (JSON)

サーバーからのレスポンスは、リクエストしたクエリの構造をそのまま反映したJSON形式になります。

{
  "data": {
    "uiapi": {
      "query": {
        "Account": {
          "edges": [
            {
              "node": {
                "Name": {
                  "value": "GenePoint"
                },
                "AnnualRevenue": {
                  "displayValue": "$30,000,000"
                },
                "Contacts": {
                  "edges": [
                    {
                      "node": {
                        "FirstName": {
                          "value": "Edna"
                        },
                        "LastName": {
                          "value": "Frank"
                        }
                      }
                    }
                  ]
                }
              }
            },
            {
              "node": {
                "Name": {
                  "value": "United Oil & Gas, Corp."
                },
                "AnnualRevenue": {
                  "displayValue": "$2,700,000,000"
                },
                "Contacts": {
                  "edges": [
                    {
                      "node": {
                        "FirstName": {
                          "value": "Ashley"
                        },
                        "LastName": {
                          "value": "James"
                        }
                      },
                      {
                        "node": {
                          "FirstName": {
                            "value": "Tom"
                          },
                          "LastName": {
                            "value": "Ripley"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          ]
        }
      }
    }
  }
}

このように、1回のリクエストで、必要なデータだけを、望んだ階層構造で取得できていることがわかります。

注意事項

GraphQL APIは非常に強力ですが、利用する上でいくつか注意すべき点があります。

権限 (Permissions)

GraphQL APIは、実行ユーザーの権限を完全に尊重します。オブジェクトへのアクセス権、項目レベルセキュリティ（Field-Level Security - FLS）、共有ルールなど、Salesforceの標準的なセキュリティモデルが全て適用されます。ユーザーがアクセスできないフィールドをクエリに含めた場合、そのフィールドはnullとして返されるか、エラーが発生します。統合ユーザーのプロファイルと権限セットを適切に設定することが不可欠です。

API制限 (API Limits)

GraphQLクエリは、1回のリクエストでどれだけ複雑なデータを取得できたとしても、SalesforceのAPIコール消費量としては「1回」としてカウントされます。これは非常に効率的ですが、無制限に利用できるわけではありません。クエリの複雑さ（ネストの深さ、要求するノード数など）にはガバナ制限が適用されます。複雑すぎるクエリはパフォーマンスの低下を招くだけでなく、エラーを引き起こす可能性があります。設計段階で、クエリが過度に複雑にならないよう注意が必要です。

エラー処理 (Error Handling)

GraphQLのレスポンスは、REST APIとは少し異なるエラーハンドリングの考え方を持っています。HTTPステータスコードは、リクエストがサーバーに到達し、正常に処理された場合は通常 `200 OK` を返します。しかし、`200 OK` であっても、レスポンスボディ内に `errors` 配列が含まれている場合があります。これは、クエリの一部が成功し、一部が失敗した場合（例：アクセス権のないフィールドを要求した）に発生します。統合を実装する際は、レスポンスの `data` 部分だけでなく、必ず `errors` 配列の有無もチェックするロジックを組み込む必要があります。

トランザクションとサポート範囲

現状のSalesforce GraphQL APIは、主にデータの読み取り（Query）に最適化されています。データの書き込み（Mutation）も可能ですが、複雑なトランザクション制御や、複数の異なるsObjectを一度のMutationで操作するような高度なユースケースには、Apex REST APIなど他の選択肢が適している場合があります。また、全てのsObjectや機能がGraphQL APIでサポートされているわけではないため、利用前に公式ドキュメントでサポート範囲を確認することが重要です。

まとめとベストプラクティス

Salesforce GraphQL APIは、特にフロントエンドアプリケーションや外部システムとのデータ連携において、従来のREST APIが抱えていたOver-fetchingやUnder-fetchingといった課題を解決する、非常に効果的なソリューションです。

統合エンジニアとしてのベストプラクティスを以下にまとめます。

適切なAPIの選択: 複数の関連オブジェクトにまたがる複雑なデータ構造を一度に読み取りたい場合は、GraphQL APIが最適です。一方、単一のレコードに対するシンプルなCRUD操作や、大量のデータを一括で処理する場合には、それぞれREST APIやBulk API 2.0の方が適している場合があります。目的に応じて最適なAPIを使い分けましょう。
クエリの最適化: クライアントが必要とするフィールドのみを明示的に指定し、不要なデータは決して要求しないようにします。また、クエリのネストが深くなりすぎないように注意し、パフォーマンスへの影響を常に考慮します。
堅牢なエラーハンドリングの実装: レスポンス内の`errors`配列を常に確認し、部分的な失敗にも対応できるクライアントロジックを実装します。
開発ツールの活用: GraphiQLやPostmanなどのGraphQLクライアントツールを活用して、開発中にクエリのテストやスキーマの探索を効率的に行いましょう。これにより、開発サイクルを大幅に短縮できます。

GraphQL APIを適切に活用することで、私たちはよりパフォーマンスが高く、効率的で、保守性に優れたシステム統合を構築できます。これは、現代の複雑なアプリケーション要件に応えるための、我々のツールボックスに加わった強力な武器と言えるでしょう。

にゃんこのSalesforce日記

このブログを検索