JA 地球アイコン
ユーザーアイコン
このページ
  • 最終編集日時: 25 July 2022
何かお探しですか？ 製品 Coupa製品ドキュメント インテグレーション技術文書 Coupa Core API APIの開始 GraphQLの紹介

GraphQLの紹介

はじめに

GraphQLは、APIクエリ言語（つまり「QL」参照）のオープン仕様であり、必要なデータのみを要求する機能を提供することで、インテグレーションの応答性を従来よりも高めることができます。GraphQLでは、1回の呼び出しで必要なすべてのリソースを取得することで、呼び出しの回数と関連付けられたラウンドトリップの回数を減らすこともできます。または、呼び出しの回数を減らすことができます。 

つまり、GraphQLは、応答ペイロードのサイズや実行されるコール数に起因する帯域幅オーバーヘッドを削減することで、インテグレーションに大きな影響を与えます。

メモ

APIフィルターは引き続き重要な機能であり、REST API GET呼び出しを行う際のリソース使用量を削減するために引き続き使用する必要があります。

OIDC/OAuth2

CoupaのGraphQLクエリーエンドポイントはOIDCを使用して認証され、承認はOAuth2スコープを使用して処理されます。 [設定]>[インテグレーショ ン]>[Oauth2/OpenID接続クライアント ]に移動し、[作成]ボタンをクリックして(または[ /oauth2/clients/new]に移動して)、クエリに適したOAuth2読み取り範囲を使用してOIDCクライアントを作成します（書き込みはまだサポートされていません）。現在サポートされているのは、クライアント認証情報の付与タイプのみです。

create-client.png

OIDCクライアントの作成後、OIDCクライアント情報を使用してアクセストークンを取得します。アクセストークンの取得方法については説明しません。OIDCクライアント情報を使用してアクセストークンを取得する手順については、Coupa管理者またはCoupaサポートにお問い合わせください。

GraphQLクライアント

アクセストークンを取得した後は、CoupaにGraphQLリクエストを作成するために使用できる多くのツールがあります。これらのツールには、curl、Postman、GraphiQLなどがあります。 

以下の例では、GraphQLを使用します。 GraphQLを使用する主な利点の1つは、スキーマをフェッチし、ユーザーフレンドリーな方法でスキーマを探索できることです。

https://www.electronjs.org/apps/graphiqlからGraphiQLをダウンロ ードするか、HomebrewがインストールされているMacユーザーの場合は、次のコマンドを使用します。

brew install --cask graphiql

GraphiQLのインストール後に起動すると、次の図のようになります。

graphiiQ.png

上の画像の注意点：

  • インスタンスURLを入力し、GraphQLエンドポイ /api/graphqlントバー にを追加します 。
  • HTTPヘッダーを編集して、アクセストークンを承認ヘッダーに追加します（以下の画像を参照）。
  • スキーマを表示するに は、[ドキュメント]をクリックして展開します。

ヘッダーを編集する場合は、[ヘッダーを追加]ボタンをクリックして 承認ヘッダーを追加し 、次の情報を入力します。

ヘッダー名：承認
ヘッダー値：bearer {your access token}

ヘッダー値の前にが付いていることを確認 bearerしてください。付いていない場合、承認できません。

auth-header.png

スキーマ

GraphiQLでドキュメントを展開すると、スキーマを調べることができます。スキーマを使用すると、クエリ可能な内容とクエリの戻り値の型を確認できます。

警告

突然変異はサポートされておらず、使用すべきではない。

クエリ

GraphQLを使用すると、必要なデータに特化したクエリを実行できます。単一のオブジェクトまたはオブジェクトのコレクションのデータをクエリーできます。

単一オブジェクト

単一のオブジェクトを問い合わせるには、小文字でオブジェクト名の単数形を使用し、オブジェクトIDを指定します。たとえば、user(id: 1)、expenseReport(id: 1)です。

single-object.png

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

コレクション

オブジェクトのコレクションを問い合わせるには、オブジェクト名の複数形を小文字で使用します。 例えば 、users、expenseReports。

collections.png

関連付け

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

associations.png

上の画像は、単一の経費レポートのクエリを示しています（これはオブジェクトのコレクションにも機能します）。経費レポートでは、誰が作成したのか、レポートの経費品目に関する追加情報を照会しています。経費品目内でも、ネストされたデータを照会していることに注意してください。

カスタムフィールド

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

custom-fields.png

カスタムフィールドは、任意のタイプ（テキスト、日時、ユーザーなど）にすることができます。[カス タムフィールド ]フィールドを使用すると、特定のカスタムフィールドのタイプを確認できます。これにより、フラグメントを使用して具体的にそれらのタイプをクエリできます。

フラグメント

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

fragments.png

上の例では、2つのフラグメントを指定します。 ... on User { ... } と.. on StringValue { ... }.  フラグメントは、カスタムフィールドを指定されたタイプに変換するようCoupaに指示します（該当する場合）。指定されたタイプに変換できる場合、要求されたフィールドが返されます。

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

コレクションクエリには、クエリと呼ばれる追加のオプションパラメーターがあり 、応答をさらにフィルタリングします。queryオプションの形式は、REST APIで値を除外するためにも使用されるクエリ文字列パラメーターの形式になっています 。

advanced-filtering-querying.png

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

エラー

応答を確認する際は、JSON応答にエラーがあるかどうかを常に確認する必要があります。エラーがある場合、メッセージとエラーの詳細が表示されます。

errors.png

イントロスペクション

スキーマ自体について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
		name
		ofType {
			kind
			name
			ofType {
				kind
				name
			}
		}
	}
}

				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
			name
			ofType {
				kind
				name
				ofType {
					kind
					name
				}
			}
		}
	}

Postmanを使用したGraphQL

上記のすべてのGraphQLの例は、次の手順に従ってPostman で実行することもできます。

  1. CoupaでOIDCトークンを生成します。詳細につ いては、「OAuthの使用を開始する 」を参照してください。
  2. アクセストークンが生成されたら、それを使用して次のPOSTMAN設定でGraphQLリクエストを開始します。
    pm-gql-01.png

    pm-gql-02.png

重要な注意事項

  • すべての申請はPOST申請です
  • すべての回答はJSONのみである
  • 返答コード200が返された場合でも、常に返答の本文でエラーを確認してください

このページに表示されている一部、または全ての内容は、機械翻訳によるものです。ご了承ください。

関連アイテム

Coupa Core API

CoupaのRESTful APIは、お客様のデータをCoupaプラットフォームで読み取り、編集し、統合するための堅牢なアクセスを提供します。

詳細情報

APIの開始

Coupa APIの使用に関する一般情報、およびCSVの使用を検討するタイミング。

詳細情報

OAuth 2.0およびOIDCへの移行

Coupaは従来のAPIキーを廃止し、OAuth 2.0 / OIDCの使用を必要としています。R34以降、新しいAPIキーは発行されず、R35ではAPIキーはサポートされなくなります。

詳細情報

リソース

参照データ、トランザクションデータ、共有リソースなど、オブジェクトのタイプ別にAPIエンドポイントを整理しました。

詳細情報