ColdFusion の GraphQL について、REST、GraphQL スキーマ、変数、およびパラメーターとの違いについて説明します。
GraphQL は、API データに必要なすべての情報を提供し、クライアントが必要な情報を正確にリクエストできるようにします。
GraphQL API の利点には、次のようなものがあります。
- 一度に複数のデータソースをクエリすることができます。
- 必要なデータのみを取得します。
- データの変更や追加を容易に行えます。
REST は web サービスを作成するアーキテクチャスタイルですが、GraphQL は API のクエリ言語です。
GraphQL は、特定のデータをクエリし、必要なデータのみを取得できるので、REST より格段に優れています。REST ベースの API とは異なり、GraphQL はデータの戻り値をカスタマイズできるようにします。また、クエリ構造が返される JSON の構造に似ています。
アンダーフェッチとオーバーフェッチ
ユーザーの帯域幅が制限されていることがわかっている場合は、GraphQL を使用して、複数のリクエストを行わずに、必要なデータを正確にリクエストできます。
データ転送の最適化
クライアント負荷が高いアプリケーションを使用しており、クライアントとサーバー間のデータ転送を最適化する必要がある場合に、GraphQL を使用できます。
消費帯域幅の減少
GraphQL は、単一の API 呼び出しを行って正確なデータを取得するので、消費する帯域幅が少なくなります。そのため、帯域幅を最適化したい場合に使用できます。これは、ソーシャルメディア、メッセージング、SMS ベースのプログラムなど、非常に大きな冗長アプリケーションを扱う場合に役立ちます。
GraphQL リクエスト文字列は、GraphQL ドキュメントと呼ばれます。次に例を示します。
{
author {
id
name
}
}
GraphQL クエリをページに読み込んでクエリとして使用するか、コード内にクエリをインラインで記述することで、GraphQL クエリを利用できます。
GetGraphQLClient
シンタックス
getGraphQLClient(parameterStruct)
説明
このメソッドを使用して、スキーマを含むサーバーと通信する GraphQL クライアントを作成します。設定パラメーターを渡して、クライアントを取得します。
パラメーター
| パラメーター | 説明 | 必須 |
|---|---|---|
| service_url | スキーマを含むサーバーの URL。独自のサーバーを作成することも、既存のサーバーを使用することもできます。詳細については、次の資料を参照してください。 | はい |
| service_name |
サーバーの名前を指定します。 |
はい |
| client_name | ColdFusion Administrator で設定した GraphQL クライアントの名前。ColdFusion Administrator で GraphQL サービスを設定する方法について詳しくは、GraphQL オプションを参照してください。 | はい |
| raw_http_client |
（True/False）内部的に HTTP クライアントまたは Apollo クライアントを使用する必要があるかどうかを指定する属性。 |
いいえ |
| root_package_name |
サーバーのルートを指定します。例えば、サーバーが 2 台ある場合は、cfusion/gql/main/src に両方のフォルダーを作成し、pom.xml でそのフォルダーを参照します。ルートフォルダーは、GraphQL サービスごとに一意である必要があります。 |
いいえ |
| headers | 次の内容を含む構造体。
|
はい |
| batching_configuration |
GraphQL クライアントでは、1 つの HTTP 呼び出しで複数の操作を実行できるようにすることで、ネットワークの往復回数を削減するために、バッチ処理が必要とされています。 パラメーターは、次の構造体です。
バッチ処理が必要な場合は、「有効」にする必要があります。残りはオプションです。 |
いいえ |
| Subscription_configuration |
次のような構造体。
サブスクリプションが必要な場合は、websocket_url が必要です。 |
いいえ |
例外
| 例外 | 説明 |
| ValidationException |
設定が null または正しくない場合。 |
| ModuleNotAvailableException |
GraphQLClient モジュールがインストールされていない場合。 |
次に例を示します。
inline
// GQL オブジェクトの作成
gqlClient = getGraphQLClient({
service_url : "ENDPOINTURL",
"raw_http_client" : true
});
// この変数は GQL クエリを保持
Gql = ‘
query
{
Table
{
Column1
Column2
Column3
Column4
}
}
‘
// クエリからの応答を変数に割り当てて、画面にダンプできるようにする
response = gqlClient.fetchResponse(gql1, {});
ファイル
gqlClient = getGraphQLClient ({
service_name: "server-name",
type = "graphqlclient",
"raw_http_client": true,
service_url : "endpoint-url",
root_folder: "root_folder",
headers : {
values: "auth-value",
keys: "auth-key"
},
batching_configuration: {
enabled: true,
batch_interval_ms: 10,
max_batch_size: 15
},
subscription_configuration : {
websocket_url: "wss://websocket-url",
subscription_heartbeat_timeout : 5,
subscription_heartbeat_timeunit : "nano"
}
})
GenerateGraphQLModels
シンタックス
generateGraphQLModels()
説明
このメソッドでは、すべてのクエリ、ミューテーション、およびサブスクリプションのモデルが生成されます。クエリー変更がある場合、または graphql ファイルに新しいクエリを追加した場合は、毎回このメソッドを呼び出します。
エラーが発生した場合は、ColdFusion を停止し、Felix キャッシュ（ CFHOME\cfusion\bin\felix-cache）をクリアして、ColdFusion を再起動します。
GraphQL オブジェクトのメソッド
GraphQL オブジェクトには、fetchResponse というメソッドが含まれています。このメソッドは、指定されたクエリのサーバーへの応答を取得します。
シンタックス
fetchResponse(query, queryParams)
パラメーター
- query：サーバーに渡されるクエリ、サブスクリプション、またはミューテーション。
- queryParams：クエリパラメーターとして渡す値。
例外
- org.apache.maven.shared.invoker.MavenInvocationException
次に例を示します。
paramValues = ${id:[89,109,189,200,205]};
response = gqlclient.fetchResponse("mutation BookTrip($id:[ID]!){bookTrips(launchIds:$id) {success message}}", paramValues);
GraphQL クライアントメソッド
サポートされているメソッドは次のとおりです。
| メソッド | パラメーター | 戻り値 |
|---|---|---|
| activeCallsCount() |
なし | クエリに対して実行された呼び出しの数 |
addOnSubscriptionManagerStateChangeListener (com.apollographql.apollo.subscription.OnSubscriptionManagerStateChangeListener) |
クロージャ関数 | なし |
| disableSubscriptions() |
なし | なし |
| downloadSchema(java.lang.String, java.lang.String) |
クエリのスキーマ | なし |
| enableSubscriptions() |
なし | なし |
| getApplicationInterceptorFactories() |
なし | リスト |
| getApplicationInterceptors() |
なし | リスト |
| getName() |
なし | クエリ名 |
| getSchema(java.lang.String) |
なし | GraphQL スキーマを返します |
| getServerUrl() |
なし | GraphQL サーバーの URL |
| getSubscriptionManager() |
なし | サブスクリプションマネージャー |
| getSubscriptionManagerState() |
なし | サブスクリプションマネージャーの状態。 |
| mutation(java.lang.String, java.lang.Object) |
|
ミューテーションオブジェクト |
| query(java.lang.String, java.lang.Object) |
|
クエリオブジェクト |
| serverOk() |
なし | サーバーの状態、サーバーが稼働している場合は True、それ以外の場合は False |
| shutDown() |
なし | なし |
| startBatchPoller() Non |
なし | なし |
| stopBatchPoller() |
なし | なし |
| subscribe(java.lang.String, java.lang.Object) |
|
なし |
Query/Mutation/Subscription object
操作のオブジェクトを取得するには、getGraphQLClient という関数のオブジェクトを作成します。例、
// 最初に graphQL サービスを取得
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
//"raw_http_client": true,
headers: {
keys: "key",
values: "value" }
});
generateGraphQLModels();
queryObj = gqlClient.query(schema,values)
クエリオブジェクトのメソッド
サポートされているメソッドは次のとおりです：
| メソッド | パラメーター | 戻り値 |
|---|---|---|
| canBeBatched(boolean) |
boolean |
クエリオブジェクトを返します。 |
| cancel() |
なし | なし |
| clone() |
なし | 操作の複製オブジェクトを返します。 |
| Enqueue(closure) |
()、execute () は queryObject メソッドで使用できます。これらは、queryObject.execute() または mutationObject.enqueue(onSuccess, onFailure) で呼び出されます。enqueue() でのクロージャは 2 つあり、1 つは成功、もう 1 つは失敗です。 |
なし |
| execute() |
なし | クエリオブジェクトからの結果を返します。 |
| fields() |
なし | クエリ応答のフィールドを返します。 |
| isCanceled() |
なし | 操作がキャンセルされた場合（True）、キャンセルされなかった場合 （False）を返します。 |
| marshalVariablesJson() |
なし | JSON データを返します。 |
| opName() |
なし | クエリ、ミューテーション、サブスクリプション操作の名前を返します。 |
| operation() |
なし | 操作の種類を返します。 |
| rawOperation() |
なし | 文字列を返します。 |
| toBuilder() |
なし | ApolloCall.Builder<T> オブジェクトを返します。 |
| variables() |
なし | 操作で使用する変数の構造体を返します。 |
ミューテーションオブジェクトのメソッド
サポートされているメソッドは次のとおりです：
| メソッド | パラメーター | 戻り値 |
|---|---|---|
| canBeBatched(boolean) 注意：ミューテーションはバッチ処理ではサポートされていません。 |
ブール値 | クエリオブジェクトを返します。 |
| cancel() |
なし | なし |
| clone() |
なし | 操作の複製オブジェクトを返します。 |
| Enqueue(closure) |
クエリ操作のロジックを処理するコールバック。例えば、OnResponse、OnFailure、OnHTTPError など。 |
なし |
| execute() |
なし |
クエリオブジェクトからの結果を返します。 |
| fields() |
なし |
クエリ応答のフィールドを返します。 |
| isCanceled() |
なし |
操作がキャンセルされた場合（True）、キャンセルされなかった場合 （False）を返します。 |
| marshalVariablesJson() |
なし |
JSON データを返します。 |
| opName() |
なし |
クエリ、ミューテーション、サブスクリプション操作の名前を返します。 |
| operation() |
なし |
操作の種類を返します。 |
| rawOperation() |
なし |
文字列を返します。 |
| toBuilder() |
なし |
ApolloCall.Builder<T> オブジェクトを返します。 |
| variables() |
なし |
操作で使用する変数の構造体を返します。 |
サブスクリプションオブジェクトのメソッド
サポートされているメソッドは次のとおりです：
| メソッド | パラメーター | 戻り値 |
|---|---|---|
| cancel() |
なし | なし |
| clone() |
なし | 操作の複製オブジェクトを返します。 |
| Execute(closure,closure,closure) |
クエリ操作のロジックを処理するコールバック。例えば、 OnResponse、OnFailure、OnHTTPError など。 |
なし |
| execute(Closure onConnected, Closure onResponse, subscriptionObject.closure onFailure,Closure onCompleted, Closure onTerminated) |
クエリ操作のロジックを処理するコールバック。例えば、 OnResponse、OnFailure、OnHTTPError など。 |
|
| isCanceled() |
なし | 操作がキャンセルされた場合（True）、キャンセルされなかった場合 （False）を返します。 |
GraphQL クライアントの設定
ColdFusion Administrator
ColdFusion Administrator を使用して GraphQL サービスを設定します。詳しくは、GraphQL オプションを参照してください。
<cfscript>
adminObj = CreateObject("component","CFIDE.adminapi.administrator");
adminObj.login("admin","admin")
gqlCFC = CreateObject("component","CFIDE.adminapi.graphql")
http_header = {
"x-hasura-admin-secret" = "secret"
}
gqlCFC.setServiceConfiguration(service_name="hasura",root_package_name="root_hasura",service_url="https://hardy-mink-39.hasura.app/v1/graphql",headers=http_header, schema_path="");
sc = {
websocket_url: "wss://hardy-mink-39.hasura.app/v1/graphql",
subscription_heartbeat_timeout : "1",
subscription_heartbeat_timeunit : "days"
}
bc = {
enabled: false
}
gqlCFC.setClientConfiguration(client_name="hasura_client_http",service_cname="hasura",raw_http_client=true,batching_configuration=bc, subscription_configuration=sc);
gqlCFC.updateServiceConfiguration(service_name="hasura",raw_http_client=true, root_package_name="updated_root");
gqlCFC.updateClientConfiguration(client_name="hasura_client_http",raw_http_client=false);
gqlFC.deleteServiceConfiguration("hasura"); Deleting service will delte clients as well
gqlFC.deleteClientConfiguration("hasura_client_http");
</cfscript>
使用する GraphQL API エンドポイントの機能は、スキーマによって制限されます。スキーマは、GraphQL エンドポイントで許可される内容を JSON で記述したものです。
スキーマは、クエリの表現として参照される項目についての説明です。GraphQL サーバーの実装は、GraphQL スキーマを中心に構築されます。GraphQL サーバの機能（クエリ、変更、サブスクリプションの範囲、使用できる追加の型やディレクティブなど）の概要を説明します。
バックエンドのデータストレージから入力されたフィールドを含む型の階層は、スキーマによって定義されます。また、クライアントがサーバーにアクセス、書き込み、削除できるデータについても説明します。
スキーマの基本的な概念
GraphQL スキーマ GraphQL SDL（スキーマ定義言語）を作成します。これは、GraphQL スキーマ言語とも呼ばれます。
スキーマは、型のコレクションとそれらの間の関係を定義します。GraphQL には 4 つの基本的な型があります。
- スカラー
- オブジェクト - クエリ、ミューテーション、サブスクリプション
- 入力
- 列挙
GraphQL スキーマの記述
スキーマを記述する前に、以下のものを準備してください。
- 構造とフィールド
- フィールドの型と戻り値の型
- 操作の種類、クエリ、ミューテーション、またはその両方
次の例では、Person という単純な型を、スキーマを使用して定義します。
type Person {
name: String! age: Int! }
このスキーマには、「name」および「age」の 2 つのフィールドがあり、データ型はそれぞれ String と Int です。
また、Person も Post の一部になることができます。
type Post {
title: String! author: Person! }
詳しくは、GraphQL スキーマを参照してください。
GraphQL の操作
次に、GraphQL 操作の種類を示します。
- クエリ（読み取り専用のフェッチ）
- ミューテーション（書き込みの後にフェッチ）
- サブスクリプション（イベントに応答して、データをフェッチするリクエスト）
クエリ
GraphQL クエリは、REST GET 呼び出しのようにアプリケーションサーバーからデータを取得します。GraphQL クエリは、次のような幅広いユースケースに対応しています。
- 表示される一連の製品。
- 顧客データの表示。
- 買い物かごの内容。
クエリの構造
クエリには、次の要素が含まれています。
- オプションのキーワードクエリ。
- ローカル実装の操作名。変数が含まれている場合は、この名前が必須です。
- クエリ名。
- 検索対象となる用語。
- クエリが返すデータを指定する出力オブジェクト。
次の例は、買い物かごクエリの構造を示しています。
query myCartQuery{
cart(cart_id: String!): Cart
}
上の例の MyCartQuery は、買い物かごクエリの実装方法を示しています。null 非許容値の買い物かご ID を含む文字列は、クエリする買い物かごを識別します。感嘆符で表示されているように、値に null 値を指定することはできません。返されるフィールドは、買い物かご出力オブジェクトによって指定されます。
クエリ全体を次に示します。
query myCartQuery{
cart(cart_id: "1WxKm8WUm3uFKXLlHXezew5WREfVRPAn") {
items {
id
quantity
}
billing_address {
firstname
lastname
postcode
}
shipping_addresses {
firstname
lastname
postcode
}
}
}
次の例は、クエリ応答を示しています。
{
"data": {
"cart": {
"items": [
{
"id": "7",
"quantity": 10
}
],
"billing_address": {
"firstname": "James",
"lastname": "Spencer",
"postcode": "12345"
},
"shipping_addresses": [
{
"firstname": "James",
"lastname": "Spencer",
"postcode": "12345"
}
]
}
}
}
クエリを定義する際は、次のことも実装できます。
非同期と同期
ColdFusion は、GraphQL での非同期操作をサポートしています。これにより、クライアントで操作を実行したり、同時スレッドで操作を実行したりできます。例,
onSuccess = function(response) {
writeOutput("Received Response from GraphQL Server");
writedump(response.toString());
}
onError = function() {
writeOutput("Error While Receiving Response from GraphQL Server");
}
queryObj = gqlClient.query("Warriors", {});
// async call
queryObj.enqueue(onSuccess, onError);
// sync call
writedump(queryObj.execute())
非同期バージョンでは、クエリおよびミューテーション操作に対して、次のようなコールバックメソッドが用意されています。
- onSuccess
- onFailure
サーバーが成功した場合は、onSuccess コールバックが呼び出されます。それ以外の場合は、onFailure コールバックが呼び出されます。
GraphQL の変数
次の例に示すように、変数を渡します。
query ($limit: Int) {
author(limit: $limit) {
id
name
}
}
The variable can be set in the following way:
{
limit: 5
}
GraphQL の変数
GraphQL では、ミューテーションを含むデータの挿入、更新、または削除を行うことができます。ミューテーションとは、サーバー側でデータを変更できるようにする GraphQL の操作です。GraphQL のミューテーションは、REST における POST、PUT、PATCH、DELETE リクエストのようなものと考えることができます。
次に例を示します。
mutation {
addCategory(id: 6, name: "Green Fruits", products: [8, 2, 3]) {
name
products {
name
}
}
}
サブスクリプション
サブスクリプションは、新規オブジェクトの作成や重要なフィールドの更新など、バックエンドデータの変更をクライアントにリアルタイムで通知するのに役立ちます。
次に例を示します。
type Subscription {
commentAdded(postID: ID!): Comment
}
On the client side,
subscription OnCommentAdded($postID: ID!){
commentAdded(postID: $postID) {
id
content
}
}
サブスクリプションの仕組み
サブスクリプションは WebSocket を使用して、サーバーからクライアントへのリアルタイム通信を設定します。サブスクリプションは、クエリがサーバー上のデータを作成、読み取り、更新、または削除する際に WebSocket をリッスンします。イベントがサーバーからサブスクライビングしているクライアントにプッシュされます。
サポートされているコールバック関数は以下のとおりです。
- public void execute(Closure onResponse, Closure onFailure, Closure onCompleted);
- public void execute(Closure onConnected, Closure onResponse, Closure onFailure,Closure onCompleted, Closure onTerminated)
次に例を示します。
<cfscript>
//Subscription Client Handle Creation
subscrClient = getGraphQLClient({
url = <graphql_server_url>,
webSocketServerUrl = <websocket_server_url>,
wsprotocol = <websocket_protocol>,
subscriptionTrasportFactory = <subscription_transport_factory>,
headers = <ok_http_client>
...
});
subscriptionHandlerCallback = <Callback to Handle the OnCompleted/OnConnected/OnTerminated/OnResponse/OnFailure Logic for Subscription Operation>
subscriptionCall = subscrClient.subscribe(subscriptionObj);
subscriptionCall.execute(subscriptionHandlerCallback);
</cfscript>
ColdFusion の GraphQL
このリリースでは、ColdFusion のフルバージョンをインストールすると、GraphQL パッケージが自動的にインストールされます。
Graphql ファイルに名前を付ける場合、指定された操作の名前は、クエリ オブジェクトの形成時に指定された操作名と一致する必要があります。
GraphQL ファイルの場所
このドキュメントでは、例に Apollo サーバーを使用しています。
If {cfusion.home} is the location of ColdFusion home, then:
- For service1, all .graphql files need to be placed in {cfusion.home}/src/main/graphql/service1 directory.
- For service2, all .graphql files need to be placed in {cfusion.home}/src/main/graphql/service2 directory.
「myservice」は、graphqlclient パッケージにパッケージ化されているサービスです。「myservice」の xml エントリも pom.xml に一覧表示されます。独自のサービスを作成する場合は、同じディレクトリ（/cfusion/gql/src/main/graphql/{new_gql_service_name}）にフォルダーを作成し、pom.xml ファイルを変更して新しいサービスを追加します。
pom.xml の変更点
pom.xml（ColdFusion/cfusion-home/gql）は、追加されたサービスエンドポイントエントリで上書きされます。
<myservice>
<compilationUnit>
<name>myservice</name>
<compilerParams>
<rootPackageName>root</rootPackageName>
</compilerParams>
</compilationUnit>
<introspection>
<enabled>true</enabled>
<endpointUrl
>https://apollo-fullstack
tutorial.herokuapp.com/graphql</endpointUrl
>
<headers></headers>
<connectTimeoutSeconds>10</connectTimeoutSeconds>
<readTimeoutSeconds>10</readTimeoutSeconds>
<writeTimeoutSeconds>10</writeTimeoutSeconds>
<useSelfSignedCertificat>false</useSelfSignedCertificat>
<useGzip>false</useGzip>
<prettyPrint>false</prettyPrint>
</introspection>
</myservice>
HTTP クライアントおよび Apollo クライアント
Apollo クライアントでは、クエリを記述して、作成したサービスフォルダーにクエリを配置できます。次に、cfm ファイルでメソッド generateGraphQLModels() を呼び出し、応答を生成します。
HTTP クライアントを使用すると、クエリをコンパイルせずにクエリを直接作成および編集できます。HTTP クライアントでは、サブスクリプションはサポートされていません。さらに、クライアント側でのパラメーターの型チェックは、HTTP クライアントでは実行されません。
クエリ
クライアントは、クエリを使用して、必要なデータをサーバーにリクエストします。
次に例を示します。
起動回数を計算します。
<cfscript>
// get the graphQL service first
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
headers : {
keys: "Authorization",
values: "value"
}
});
generateGraphQLModels();
queryObj = gqlClient.query("MissionDetails", {});
response=queryObj.execute()
response.get("Data")
</cfscript>
同様に、予約された旅行の数を計算します。
<cfscript>
// 最初に graphQL サービスを取得
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
headers : {
keys: "Authorization",
values: "value"
}
});
generateGraphQLModels();
queryObj = gqlClient.query("TripsBooked", {});
//writedump(queryObj);
response=queryObj.execute()
// writeDump(response.get("Data"))
</cfscript>
出力
{totalTripsBooked=9}
サブスクリプション
TripsBookedSub.graphql
subscription TripsBookedSub {
tripsBooked
}
File.cfm
<cfscript>
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
headers : {
keys: "Authorization",
values: "value"
}
});
generateGraphQLModels();
queryObj=gqlClient.subscribe("TripsBookedSub",{})
// writeDump(queryObj)
</cfscript>
ミューテーション
ミューテーションは、指定できるフェッチを返します。応答なしにミューテーションすることはできません。
ユーザーログインを追加します。
Login.graphql
mutation Login($email: String) {
login(email: $email) {
token
}
}
mutation.cfm
<cfscript>
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
//"raw_http_client": true,
headers : {
keys: "key",
values: "value"
}
});
generateGraphQLModels();
queryObj = gqlClient.mutation("Login", {
"email": "user1@example.com"
});
// writedump(queryObj)
response=queryObj.execute()
// writeDump(response.get("Data"))
</cfscript>
出力
{
login=Login{
__typename=User, token=<token>
}
}
フラグメント
フラグメントは再利用可能なクエリコンポーネントであり、GraphQL フラグメントです。GraphQL では、異なるクエリを使用して同じフィールドを検索する必要がある場合があります。クエリに複数の異なる場所に散在する繰り返しフィールドが多数含まれている場合は、それらを結合して、フラグメントと呼ばれる単一の再利用可能な単位にすることができます。
次の例は、任意の Employee オブジェクトでも使用できる EmpName フラグメントの宣言です。
fragment EmpName on Employee {
firstName
lastName
}
次に例を示します。
LaunchDetailsFragment.cfm
fragment launchFragment on Launch {
id
site
mission {
name
}
}
query LaunchDetailsFragment($id:ID!){
launch(id: $id) {
# Usage of named fragment
...launchFragment
}
}
Fragments.cfm
<cfscript>
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
headers : {
keys: "key",
values: "value"
}
});
generateGraphQLModels();
queryObj = gqlClient.query("LaunchDetailsFragment", {"id": "50"});
// writedump(queryObj)
response=queryObj.execute()
// writeDump(response.get("Data"))
</cfscript>
出力
{launch=Launch{__typename=Launch, fragments=Fragments{launchFragment=LaunchFragment{__typename=Launch, id=50, site=KSC LC 39A, mission=Mission{__typename=Mission, name=KoreaSat 5A}}}}}
インラインパラメーター
GraphQL の ColdFusion 実装では、クエリとパラメーターを CFML コード内で直接インラインで渡すことができます。これにより、デバッグ時の読みやすさが向上するだけでなく、CF スコープからクエリパラメーターに変数を渡すことも容易になります。
次に例を示します。
<cfscript>
// 最初に graphQL サービスを取得
gqlClient = getGraphQLClient({
service_Url : " https://apollo-fullstack-tutorial.herokuapp.com/graphql ",
"raw_http_client": true,
headers : {
keys: "key",
values: "value"
}
});
paramValues = ${launchId: 1}; // define the values to be passed in the query
response = gqlclient.fetchResponse("
query TripsBooked($launchId: ID!){
launch(id: $launchId) {
id
isBooked
mission {
name
}
}
}
",paramValues);
writeOutput(response.get("Data"))
</cfscript>
出力
{"data":{"launch":{"id":"1","isBooked":false,"mission":{"name":"FalconSat"}}}}
ページネーション
GraphQL では、1 つのクエリでサーバーから必要なデータフィールドをすべて取得し、ネットワーク応答時間とペイロードサイズの点で不要なオーバーヘッドを排除します。ただし、特に予測できない長さの構造化データのリストを扱う場合には、このような機能強化が常に機能するという保証はありません。無制限の数の要素が含まれる可能性がある完全なリストを要求すると、ペイロードが非常に大きくなり、応答が遅れる可能性があります。これを解決するには、ページネーションを使用するか、リストを選択的にクエリします。
次に例を示します。
teacher {
name
students (first:5) {
name
}
}
}
引数のリミットとオフセットを使用して、一度に 1 ページずつ結果を表示します。
次に例を示します。
students (limit:5, afterID:152) {
id
name
}
バッチ処理
GraphQL クライアントでは、ネットワーク内の往復回数を減らすためにバッチ処理が必要でした。バッチ処理は、1 つの HTTP 呼び出しで複数の操作を有効にすることによって実行されます。
デフォルトでは、バッチ処理されたクライアントのすべての操作について、バッチ処理が有効になりますが、execute メソッドを呼び出す前に、canbeBatched(false) 操作を呼び出すことで操作をオプトアウトできます。
バッチ処理は、クエリ操作に対してのみ使用できます。
ColdFusion では、以下のバッチ処理パラメーターがサポートされています。
"batching_configuration":{
"enabled": true, // クエリ、ミューテーション、サブスクリプションのバッチ処理を有効にするかどうか
"batch_interval_ms": 1000, // 各呼び出し間の間隔（ミリ秒単位）
。"max_batch_size": 2 //
}
バッチ関数
次のバッチ関連関数がサポートされています。
startBatchPoller
説明
ポーリングメカニズムを開始して、キューに入れられたクエリを確認してバッチ化し、単一の HTTP 呼び出しとして送信します。この機能を使用するには、バッチ設定で「enabled」:true を有効にする必要があります。
シンタックス
gqlClient.startBatchPoller()
次に例を示します。
<cfscript>
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
//"raw_http_client": true,
headers : {
keys: "Authorization",
values: "a2FsbHVAZ21haWwuY29t"
},
"batching_configuration":{
"enabled": true,
"batch_interval_ms": 1000,
"max_batch_size": 2
}
});
generateGraphQLModels();
writedump(gqlClient)
queryObj = gqlClient.query("TripsBooked", {})
writedump(queryObj);
response=queryObj.execute()
writeDump(response.get("Data"))
// エラーおよび成功のクロージャ関数を定義
onSuccess = function(response) {
writeOutput("<br>Received Response from GraphQL Server----------<br>");
writeOutput(response.toString());
}
onError = function() {
writeOutput("<br>Error While Receiving Response from GraphQL Server<br>");
}
writeOutput("<br/>"& "Active calls count" & "<br/>")
writeOutput(gqlClient.activeCallsCount())
writeOutput("<br/>"& "Can be batched" & "<br/>")
gqlClient.startBatchPoller();
queryObj.canBeBatched(true)
</cfscript>
stopBatchPoller
説明
ポーリングメカニズムを停止して、キューに入れられたクエリのバッチ処理を確認します。この機能を使用するには、バッチ設定で「enabled」:true を有効にする必要があります。
シンタックス
gqlClient.stopBatchPoller()
次に例を示します。
<cfscript>
gqlClient = getGraphQLClient({
service_url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
//"raw_http_client": true,
headers : {
keys: "key",
values: "value"
},
"batching_configuration":{
"enabled": true,
"batch_interval_ms": 1000,
"max_batch_size": 2
}
});
generateGraphQLModels();
writedump(gqlClient)
queryObj = gqlClient.query("TripsBooked", {})
writedump(queryObj);
response=queryObj.execute()
writeDump(response.get("Data"))
// エラーおよび成功のクロージャ関数を定義
onSuccess = function(response) {
writeOutput("<br>Received Response from GraphQL Server----------<br>");
writeOutput(response.toString());
}
onError = function() {
writeOutput("<br>Error While Receiving Response from GraphQL Server<br>");
}
writeOutput("<br/>"& "Active calls count" & "<br/>")
writeOutput(gqlClient.activeCallsCount())
writeOutput("<br/>"& "Can be batched" & "<br/>")
gqlClient.startBatchPoller();
queryObj.canBeBatched(true)
gqlClient.stopBatchPoller();
</cfscript>
canBeBatched(bool)
説明
クエリをバッチ処理できるかどうかを決定します。
シンタックス
GqlClient.canBeBatched(bool batchedTrueOrFalse)
パラメーター
batchedTrueOrFalse：バッチを作成する場合は True、それ以外の場合は False を指定します。
バッチ処理の例
LaunchList. graphql
query LaunchList {
launches {
cursor
hasMore
launches {
id
site
}
}
}
LaunchDetailsFragment.graphql
fragment launchFragment on Launch {
id
site
mission {
name
}
}
query LaunchDetailsFragment($id:ID!) {
launch(id: $id) {
# Usage of named fragment
...launchFragment
}
}
File.cfm
出力
<cfscript>
gqlClient = getGraphQLClient({
service_Url : "https://apollo-fullstack-tutorial.herokuapp.com/graphql",
root_folder: "root",
//"raw_http_client": true,
headers : {
keys: "key",
values: "value"
},
"batching_configuration":{
"enabled": true,
"batch_interval_ms": 1000,
"max_batch_size": 2
}
});
generateGraphQLModels();
writedump(gqlClient)
queryObj = gqlClient.query("LaunchList",{cursor:"1583556631"});
writedump(queryObj);
response=queryObj.execute()
writeDump(response.get("Data"))
queryObj2 = gqlClient.query("LaunchList", {cursor:""});
queryObj3 = gqlClient.query("LaunchDetailsFragment",[id:"89"]);
response3=queryObj3.execute()
writeDump(response3.get("Data"))
//queryObj4 = gqlClient.query("LaunchDetailsFragment",[id:"90"]);
gqlClient.startBatchPoller();
queryObj.canBeBatched(true);
queryObj2.canBeBatched(true);
queryObj3.canBeBatched(true);
gqlClient.stopBatchPoller();
writeOutput("Completed");
</cfscript>
出力
{launches=Launches{__typename=LaunchConnection, cursor=1583556631, hasMore=true, launches=[Launch{__typename=Launch, id=110, site=KSC LC 39A}, Launch{__typename=Launch, id=109, site=CCAFS SLC 40}, Launch{__typename=Launch, id=108, site=VAFB SLC 4E}, Launch{__typename=Launch, id=107, site=KSC LC 39A}, Launch{__typename=Launch, id=106, site=CCAFS SLC 40}, Launch{__typename=Launch, id=105, site=CCAFS SLC 40}, Launch{__typename=Launch, id=104, site=KSC LC 39A}, Launch{__typename=Launch, id=103, site=KSC LC 39A}, Launch{__typename=Launch, id=102, site=KSC LC 39A}, Launch{__typename=Launch, id=101, site=CCAFS SLC 40}, Launch{__typename=Launch, id=100, site=CCAFS SLC 40}, Launch{__typename=Launch, id=99, site=KSC LC 39A}, Launch{__typename=Launch, id=98, site=CCAFS SLC 40}, Launch{__typename=Launch, id=97, site=CCAFS SLC 40}, Launch{__typename=Launch, id=96, site=CCAFS SLC 40}, Launch{__typename=Launch, id=95, site=CCAFS SLC 40}, Launch{__typename=Launch, id=94, site=KSC LC 39A}, Launch{__typename=Launch, id=93, site=KSC LC 39A}, Launch{__typename=Launch, id=92, site=KSC LC 39A}, Launch{__typename=Launch, id=91, site=CCAFS SLC 40}]}} {launch=Launch{__typename=Launch, fragments=Fragments{launchFragment=LaunchFragment{__typename=Launch, id=89, site=CCAFS SLC 40, mission=Mission{__typename=Mission, name=Starlink 3}}}}}
