外部サービスの API 仕様の定義

学習の目的

この単元を完了すると、次のことができるようになります。

API 仕様の目的を説明する。
外部サービスでサポートされているスキーマ定義の要素について説明する。
API 仕様の失敗を引き起こす可能性がある問題を 3 つ挙げる。

スキーマ定義が必要な理由

前の単元では、API 仕様とは API が実行できる内容を定義する説明的なスキーマを含むファイルであることを学習しました。外部サービスの登録の API 仕様をあなた自身が作成する場合でも、他の誰かが作成する場合でも、API 仕様の目的と使用方法を理解しておくことをお勧めします。

REST ベースの銀行 API があると想像してください。その REST ベース API の構造を説明するための共通の標準化された形式が必要です。そこで役立つのが API 仕様です。Salesforce では、記述形式に広く採用されている OpenAPI 仕様を使用しています。

API 仕様にはスキーマ定義が含まれます。スキーマ定義では、組織が外部 Web サービスに対して行うコール (または要求) にどのような入力や出力を含めることができるかを説明します。たとえば、コールに ID を数値入力、name をテキスト出力として含めるなどです。

API 仕様には、アクセスできる REST ベースの API Web サービスのエンドポイント情報と認証パラメーターも含まれます。(前述のとおり、エンドポイントは、外部サービスがやり取りする Web サービスのリソースを公開するものです)。たとえば、次の API 仕様は架空の銀行 Web サービスの仕様ですが、口座を追加や削除するメソッドが含まれます: https://th-external-services.herokuapp.com/accounts/schema。

実際のアプリケーションでは、セキュリティのベストプラクティスに従って、銀行の API にアクセスする前に認証ステップを含めます。

架空の銀行の API 仕様は人間が判別可能な構造化されたデータです。それでは見ていきましょう。

スキーマの基本的な口座操作は次のとおりです。

パス /accounts/{accountName} での操作	説明
GET	口座を取得する
POST	口座を追加する
PUT	口座を更新する
DELETE	口座を削除する

API 仕様のスキーマから抜粋した次のスニペットには、GET メソッドに関する情報が含まれています。念のために説明すると、GET メソッドとは単に Web サービスからリソース情報を取得するものです。この特定の GET メソッドは、リソースパスを使用して口座に関する情報を取得 (“gets”) します。この場合のリソースパスは /accounts/{accountName} で、{accountName} は指定した口座です。"parameters" の下に、"name":"accountName" があります。このパラメーターは、指定した口座名と一致している必要があり、必須です ("required":true)。また、文字列形式でなければなりません。

"paths": {
	"/accounts/{accountName}":
	{ "get":
		{ "operationId": "getAccount",
		"summary": "Retrieves an account",
		"description": "Retrieves the account with specific name",
		"consumes": ["text/plain"],
		"produces": ["application/json"],
		"parameters": [{
		"name": "accountName",
		"in": "path",
		"required": true,
		"type": "string",
		"description": "Name of the account" }],
		"responses": {
			"200": {
				"description": "The response when system finds an account with given name",
				"schema": {
				"$ref": "#/definitions/accountDetails" } }, "400":
				{ "description": "Error response if the account name parameter is less than minimum characters",
			"schema":
			{ "$ref": "#/definitions/errorModel" } },
			"404": {
			"description": "Error response if the account is not supported by service or account is not found",
			"schema": { "
			$ref": "#/definitions/errorModel"
			}

これはほんの一部であり、スキーマ定義はもっとずっと大きいものです。けれども、見てわかるように、スキーマは外部サービスが使用するために設計されたものでありながら、人間も判別可能です。また、外部サービスが操作を処理して Flow Builder や Einstein ボットなどのツールで呼び出し可能アクションとして使用できるように、論理的な方法で形式設定されています。

次のステップでは、API 仕様を宣言的に登録する方法について説明しますが、その前に、有効でサポートされるスキーマ定義を構成する要素について確認しておきましょう。スキーマ定義とは、API 仕様ドキュメント内の個々の API 機能の詳しい説明です。

有効でサポートされるスキーマの構成要素は?

API 仕様の概要はわかりました。ただし、有効でサポートされるスキーマとは何を意味するのでしょうか?

OpenAPI 仕様ではスキーマ検証要件が定義されていて、外部サービスにも固有のスキーマ要件があります。その両方の要件が満たされた場合に、外部サービスはスキーマを適切にサポートし、Web サービスをコールできます。

スキーマ検証の概要

スキーマは人間が判読できますが、マシンも判読できます。外部サービスが簡単に使用できるように、スキーマは論理的な構造に従う必要があります。スキーマの構造が間違っていると、外部 Web サービスは通信できず (エラーと例外メッセージを返す)、その結果、外部サービスは外部 Web サービスを取り込めません。構造、論理、構文上の制限を満たすことは、スキーマ検証の第 1 段階として必要です。OpenAPI 仕様では、これらの一般的なルールが定義され、外部 Web サービスのコールが明確になっています。

サポートされる外部サービススキーマ

スキーマ検証のための一般的な OpenAPI ガイドラインに加えて、外部サービスに固有のスキーマ制限もあります。外部サービスに API 仕様を登録する前にその要件を確認する必要があります。外部サービスでスキーマがサポートされるということは、そのスキーマが OpenAPI 仕様に基づいて有効であり、外部サービス固有の要件にも従っているということです。たとえば、API 仕様のファイルサイズが制限を超えていたり、オブジェクトやアクションの合計数が制限を超えている場合には、登録が失敗する場合があります。

外部サービスでサポートされるスキーマを作成するための主要な要件の一覧については、Salesforce ヘルプの「外部サービスに関する考慮事項」を参照してください。

ヘルプをお探しですか?

もっと探す

外部サービスの API 仕様の定義

学習の目的

スキーマ定義が必要な理由

有効でサポートされるスキーマの構成要素は?

スキーマ検証の概要

サポートされる外部サービススキーマ

リソース