認証

CoupaのGraphQLクエリエンドポイントはOIDCを使用して認証され、認証はOAuth 2.0スコープを使用して処理されます。 詳細はOpenID Connectクライアントの設定をご参照ください。 現在サポートされているのはクライアント認証情報の付与タイプと読み取りスコープのみです。

GraphQLクライアント

アクセストークンの取得後、GraphQLリクエストを送信するために使えるツールは数多くあり、 cURL、Postman、GraphiQLなどがあります。

次の例では、GraphiQLを使用します。 GraphiQLを使う主な利点のひとつは、スキーマを取得し、それをわかりやすく便利に探索できる点です。

上の画像に関する注意点:

• インスタンスURLを指定し、 GraphQL Endpoint アドレスバーに /api/graphql を追加します。

• HTTPヘッダーを編集し、アクセストークンを承認ヘッダーに追加します(下図を参照)。

• スキーマを表示するには、文書をクリックして展開します。

ヘッダーを編集する際は、[ヘッダーを追加]ボタンと以下の情報をクリックし、承認ヘッダーを追加します。

• ヘッダー名: Authorization
• ヘッダー値: bearer {your access token}

ヘッダー値に ベアラー の接頭辞を付けるようにしてください。そうしないと、認証できなくなります。

スキーマ

GraphiQLでドキュメントを展開すると、スキーマを探索することができます。 スキーマでは、クエリ可能な要素およびクエリの戻り値の型を確認できます。

クエリ

GraphQLを使用すると必要なデータを具体的にクエリすることができます。 単一のオブジェクトまたは複数のオブジェクトのデータをクエリできます。

単一のオブジェクト

単一のオブジェクトをクエリするには、単数形かつ小文字のオブジェクト名でオブジェクトIDを指定します。 たとえば、user(id: 1)、expenseReport(id: 1)などです。

データは、クエリされたフィールドのデータとともにJSON形式で返されます。

複数のオブジェクト

複数のオブジェクトをクエリするには、複数形かつ小文字のオブジェクト名を使用します。 たとえばusers、expenseReportsなどです。

関連付け

GraphQLでは、ネストされたデータをクエリすることができます。

上の画像は、単一の経費レポートのクエリです(複数のオブジェクトでも機能します)。 経費レポートでは、作成者およびレポートの経費明細に関する追加情報をクエリしています。 経費明細内でもネストされたデータをクエリしていることにご注目ください。

カスタムフィールド

オブジェクトには、フィールド名customFieldsでクエリ可能なカスタムフィールドがある場合があります。

カスタムフィールドは、テキスト、日時、ユーザーなど、さまざまなタイプの中から指定できます。 CustomFieldsフィールドはその特定のカスタムフィールドのタイプを表示することができるため、フラグメントを使用してそのタイプを特定し、クエリを実行することが可能になります。

フラグメント

フラグメントを使用すると、フィールドのセットを構築してクエリに含めることができます。 customFieldsの場合、タイプレベルでフラグメントを指定できます。

上記の例では、2つのフラグメントを指定します。ユーザー{ …の … ｝ StringValue ｛ …の と … }. フラグメントは、カスタムフィールドを指定されたタイプに変換するようCoupaに指示します(該当する場合)。 指定されたタイプに変換できる場合、リクエストされたフィールドが返されます。

高度なフィルタリングとクエリのオプション

複数のクエリには、レスポンスをさらにフィルタリングするqueryと呼ばれる追加のオプションパラメーターがあります。 queryオプションの形式は、REST APIで値をフィルタリングする際に使用されるクエリ文字列パラメーターと同じ形式です。

上記の例では、ID値を5未満にフィルタリングするクエリパラメータとして「id [lt_or_eq] = 5」を使用しています。 これは、 /api/invoices? id [lt_or_eq] = 5の形式でREST APIに直接ドロップすることもできます。

エラー

レスポンスを確認するときは、常にJSONレスポンスにエラーがないかどうかを確認する必要があります。 エラーがある場合、エラーメッセージと詳細が表示されます。

自己照会

また、スキーマ自体についてGraphQLにクエリすることもできます。 これは、GraphQLがクライアント側でスキーマを生成する際に行う処理です。 以下は、一般的な自己照会クエリの例です。

query IntrospectionQuery {__ schema {queryType { name } mutationType { name } subscriptionType { name } types { ...FullType } directives {name description args { ...InputValue }query IntrospectionQuery {__ schema {queryType { name } mutationType { name } subscriptionType { name } types { ...FullType } directives {name description args { ...InputValue } onOperation onFragment onField}}} fragment FullType on __ Type {kind name description fields (includeDeprecated: true ){ name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason} inputFields { ...InputValue } interfaces { ...TypeRef } enumValues (includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __ InputValue {name description type { ...TypeRef } defaultValue} fragment TypeRef on __ Type {kind name ofType {kind ofType {name ofType { kind name } }} onOperation onFragment onField}}} fragment FullType on __ Type {kind description fields (includeDeprecated: true) {name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason} inputFields { ...InputValue } interfaces { ...TypeRef } enumValues (includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __ InputValue on {name type description type { ...TypeRef } Value} defaultValue Type __ Type of { { kind name } type of name}

設計上の考慮事項

• すべてのリクエストはPOSTリクエストです。

• すべてのレスポンスはJSONのみです。

• レスポンスコード200が返される場合も、常にレスポンス本文にエラーがないかを確認してください。