何かお探しですか？製品 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クライアントを作成します（書き込みはまだサポートされていません）。現在サポートされているのは、クライアント認証情報の付与タイプのみです。

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のインストール後に起動すると、次の図のようになります。

上の画像の注意点：

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

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

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

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

スキーマ

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

警告

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

クエリ

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

単一オブジェクト

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

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

コレクション

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

カスタムフィールド

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

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

フラグメント

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

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

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

コレクションクエリには、クエリと呼ばれる追加のオプションパラメーターがあり、応答をさらにフィルタリングします。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
		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 で実行することもできます。

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

重要な注意事項

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

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