ServiceNow で GraphQL API を作ってみる

外部サービス主導で ServiceNow とデータ連携しようと考えた際に、ServiceNow が提供する汎用的な REST APIs を利用したり、自身で連携の目的に最適化された REST APIs を Scripted REST APIs で作成して連携するのが一般的です。また最近では前回紹介した ServiceNow CLI というコマンドラインツールを利用して連携することも可能です。
今回は Paris バージョンから利用できるようになった GraphQL API framework を利用して独自の GraphQL APIs を作成する方法を紹介します。

GraphQL は Web Query 言語で連携に必要なデータを指定して取得することを可能にします。REST APIs の連携だとレスポンスの中には多くの不要なデータが含まれることでオーバーヘッドが生じたり、目的の情報を取得するのに何度も API コールをして取得する必要だったりするのですが、GraphQL を利用すると目的の情報をクライアントから指定することで素早く取得することが可能になります。

それでは早速作ってみましょう。今回は Developer Portal にも公開されている Need It アプリにアクセスする GraphQL APIs を作ってみます。

まず最初にやらなければならないことは GraphQL APIs の定義である GraphQL Schema Definition Language (SDL) を GraphQL API (sys_graphql_schema) テーブルに用意します。Navigator から System Web Service -> GraphQL -> GraphQL APIs モジュールにアクセスをして GraphQL API テーブルにレコードを用意します。名前を入力し、SDL を書いていきます。

SDL が用意できたら、次にここで定義した内容の実装になります。今回の例では getNeedIts で Need It アプリに存在するレコードの情報を NeedItList というタイプで返すようにしています。実装は GraphQL Scripted Resolver (sys_graphql_resolver) テーブルにしていきます。これは先ほど作成した GraphQL API レコードの関連リストから作成します。

GraphQL Scripted Resolver でロジックの実装が完了したら、最後に SDL に書いた Query との紐付けを行います。今回は getNeedIts と作成した getNeedIts というGraphQL Scripted Resolver との紐付けを行います。この紐付けは GraphQL Resolver Mappings (sys_graphql_resolver_mapping)で行います。

以上で実装は完了になります。Postman などのツールでテストを実施してみます。GraphQL APIs を実行する際の接続先は https://<インスタンス名>.service-now.com/api/now/graphql になります。Query 文は POST するボディに含めることで実行可能になります。

このように無事にデータが取得できる事を確認いただけます。連携するアプリケーションでは ID の情報は不要で Number と Name だけが取得できればいいという場合には Query を書き換える事で必要データのみを取得可能です。

このように GraphQL APIs を利用することでより柔軟に連携が実現できるようになりますので、是非とも試してみてください。
データ取得(Query)だけでなく、データ作成(Mutation)も可能ですし、Query 実行の際にパラメータを指定するような実装も可能になっているので自由度の高い連携用インターフェースを GraphQL APIs で実現が可能です。