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

学習の目的

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

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

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

外部サービスの登録の API 仕様をあなた自身が作成する場合でも、他の誰かが作成する場合でも、API 仕様の目的と使用方法を理解しておくことをお勧めします。REST ベースの 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 ヘルプの「拡張外部サービスに関する考慮事項」を参照してください。 

サポートされるスキーマを実際に詳しく見てみましょう。この次のステップでは、すべてを設定します。これは、Flow Builder や Einstein ボットなどのツールが外部 Web サービスを正常にコールできるようにするための基本的で重要な部分です。

メモ
オープンソースフレームワーク OpenAPI を使用している場合は、Swagger エディタでスキーマが OpenAPI 仕様に準拠していることを確認できます。ちょっと寄り道しても構わなければ、https://th-external-services.herokuapp.com/accounts/schema からスキーマを Swagger エディタにコピーしてみましょう。エラーが 1 つも表示されないはずです。

API 仕様に関するいくつかの概念と、一定の要件について説明しました。そろそろ外部サービスを操作してみたいと思いませんか? もちろんそうですよね。次の単元で実際に操作します。けれども先に進む前に、最初の単元で説明した最初の 2 つのステップを復習しましょう。

  1. 外部 Web サービスプロバイダが REST ベースの API 仕様を共有する: この例では架空の銀行から https://th-external-services.herokuapp.com/accounts/schema で API 仕様を受け取っています。
  2. OpenAPI 仕様に基づいて、Web サービスプロバイダ (銀行サービスの例など) または開発者 (場合によってはシステム管理者) が API を説明する JSON ベースの API 仕様を作成する: ここではこの仕様を実際に作成しませんでしたが、スキーマの要素とサポートされるスキーマの要件を確認しました。外部 Web サービスと連携するときに、システム管理者または開発者が各自のユースケースに適した API 仕様を作成できます。

リソース

無料で学習を続けましょう!
続けるにはアカウントにサインアップしてください。
サインアップすると次のような機能が利用できるようになります。
  • 各自のキャリア目標に合わせてパーソナライズされたおすすめが表示される
  • ハンズオン Challenge やテストでスキルを練習できる
  • 進捗状況を追跡して上司と共有できる
  • メンターやキャリアチャンスと繋がることができる