GraphQL

GraphQL は、既存の Autodesk Platform Services（旧 Forge）でも多く使われいる RESTful API（REST API）に比べて複雑なクエリを定義出来る機能を持つ Facebook が開発したテクノロジです。2015 年にオープンソース プロジェクトとして公開され、Linux Foundation が GraphQL.org で公開しています。

GraphQL は、API のためにデータを要求するクエリ言語（Query）と考えることができます。また、ミューテーション（Mutation）と呼ばれる動作では、データを作成、更新、および削除することも出来ます。クエリとミューテーションは同じ構文に従います。以下の例は GraphQL.org から引用したもので、Star Wars に関する情報をホストする GraphQL サーバーに送信されるクエリとミューテーションの例です。

例 1

クエリ（Query）

query HeroNameAndFriends {
  hero {
    name
    friends {
      name
    }
  }
}

結果

{
  "data":{
    "hero":{
      "name":"R2-D2",
      "friends":[
        {
          "name":"Luke Skywalker"
        },
        {
          "name":"Han Solo"
        },
        {
          "name":"Leia Organa"
        }
      ]
    }
  }
}

クエリの詳細については、Tutorial on GraphQL queries  を参照してみてください。

例 2

ミューテーション（Mutation）

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

Variables:
{
  "ep":"JEDI",
  "review":{
    "stars":5,
    "commentary":"This is a great movie!"
  }
}

結果

{
  "data":{
    "createReview":{
      "stars":5,
      "commentary":"This is a great movie!"
    }
  }
}

ミューテーションの詳細については、Tutorial on GraphQL mutations を参照してみてください。

GraphGL で扱うデータは、スキーマ（Schema Definition Language による定義）で定義されています。スキーマがわかっていれば、特定のデータを照会（クエリ）したり、変更（ミューテーション）したりすることが出来ます。これらは、必要とするデータだけをフェッチ（fetch）する動作をします。これに対して、RESTful API の場合には、必要かどうかに関係なく、すべての情報を事前定義されたペイロードを使って返す動作をします。

GraphQL の詳細については、次の内容をご確認ください：

• How to GraphQL
• Introduction to GraphQL

オートデスクがプラットフォームに位置付けているインダストリー クラウドへの GraphQL の導入が進められている状況です。これは、Data Exchange（データ交換）でも同様です。

現時点では、一部の APS API が用意されている限定された状態ですが、Data Exporter の名前がつけられたツールを使って、製造業向けに公開されている Fusion Data とデータ交換用の Data Exchange の GraphQL クエリを試すことが出来るようになっています。

• Fusion Data Explorer (autodesk.io)
• Data Exchange Data Explorer (autodesk.io)

Fusion Data Explorer で簡単な例を見てみます。Fusion Data Explorer 起動時には、3-legged OAuth を使って Fusion 360 や Fusion Team にアクセスする認可のプロセスを経て、ストレージ内のデータにアクセスします。通常、このアクセスには Data Management API の GET hubs エンドポイントを用いてアカウントに関連付けられたハブ（Hub）の ID をリストするところから情報を収集していきます。

Fusion Data Explorer の初期画面左側には、ハブ一覧を得るクエリが事前設定されています。この状態で、画面左上の再生（▶）ボタンをクリックすると、クエリが実行されて画面右側にクエリ結果（レスポンス）が表示されます。ここでは、クエリに name のみを指定しているので、ハブ名のみが一覧に表示されています。

次に、クエリに  API でハブを識別する ID（hubId）を含めるため、id を追記して（▶）ボタンをクリックすると、レスポンスに hubId が含まれるようになります。

GET hubs エンドポイントでは、アプリで使用しないケースでも定義されたデータすべてが返されるので、場合によっては冗長になってしまう場面でも、必要なデータのみを得ることが出来る訳です。ここでクエリ可能な name や id は、オートデスクがあらかじめスキーマ（schema）で定義したものある点に注意してください。

Fusion Data Explorer で GraphQL クエリを実行する際に、デベロッパーツールの「ネットワーク」タブで リクエストを監視してみると、クエリ内容が変わっても、呼び出されるエンドポイントが https://developer.api.autodesk.com/manufacturing/graphql/v1 で変わらないことがわかります。また、リクエストの「種類/タイプ」の値が、RESTful API 実行時によく見られる Ajax を使った XMLHTTPRequest 「xdr」ではなく、「fetch」になっていることも分かります（fetch ＝ GraphQL という訳ではありませんが）。

お気づきのとおり、GraphQL が持つ柔軟性によって、いままでの RESTful API で実現していた、目的に応じて異なるエンドポイントを使い分ける手間を大幅に低減させることが出来ます。言い換えれば、１つ、あるいは、少ないエンドポイント呼び出しで目的が達成出来るようになるので、トラフィックを低下させることが出来ます。キャッシュがサポートされないなどの短所もありますが、大規模で多様なデータを扱うグラフ データベースとの協調にはマッチしています。

インダストリークラウドで利用することになる GraphQL のスキーマ定義は、最終的に多くの方にお使いいただけるよう、少し時間をかけています。もちろん、扱うデータはファイルではなく、ファイルに含まれる個々のデータ、つまり、粒状データということになります。すべてのデザイン データにアクセス出来るようになるまで、少しお待ちいただければと思います。

なお、前述の Data Data Explorer  は、GitHub – autodesk-platform-services/aps-data-explorer: Data Explorer: でソースコードが公開されています。

By Toshiaki Isezaki