進行状況の追跡を始めよう
Trailhead のホーム
Trailhead のホーム

外部サービスのスキーマの定義

学習の目的

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

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

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

外部サービスの登録のスキーマをあなた自身が定義する場合でも、他の誰かが定義する場合でも、スキーマの目的と使用方法を理解しておくことをお勧めします。REST ベースの API からのスキーマの定義に精通している場合は、次のセクション「サポートされるスキーマの構成要素」に進んでください。

前に使用した給与アプリケーションと信用度サービスの REST ベースの API 外部 Web サービスの例を覚えていますか? REST ベースの銀行 API はありますが、その REST ベース API の構造を説明するための共通の標準化された形式が必要です。そこで役立つのが API スキーマ定義です。Salesforce では、記述形式に広く採用されている OpenAPI 仕様を使用しています。 

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

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

メモ

メモ

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

Salesforce のスキーマ定義は人間が読める構造化データなので、実際に見てみましょう。
スキーマの基本的な口座操作は次のとおりです。

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

スキーマ定義から抜粋した次のスニペットには、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"
            }

もちろん、スキーマについて説明すべきことはたくさんあります。けれども、見てわかるように、スキーマは外部サービスが使用するために設計されたものでありながら、人間も判別可能です。また、外部サービスがデータを処理してフローで呼び出し可能アクションとして使用できるように、論理的な方法で形式設定されています。これらのフローアクションは、この後フローの入力や出力として使用します。

次のステップは、宣言的に Web サービスを登録することです。けれどもまず、サポートされるスキーマ定義を構成する要素について説明しましょう。

サポートされるスキーマの構成要素

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

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

スキーマ検証の概要

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

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

スキーマ検証のための一般的な OpenAPI ガイドラインに加えて、外部サービスに固有のスキーマ制限もあります。外部サービスにスキーマを登録する前にこれらの要件を確認する必要があります。外部サービスでスキーマがサポートされるということは、そのスキーマが OpenAPI 仕様に基づいて有効であり、外部サービス固有の要件にも従っているということです。


外部サービスでサポートされるスキーマを作成するための主要な要件をいくつか次に挙げます。完全なリストについては、Salesforce ヘルプ: 拡張外部サービスに関する考慮事項」を参照してください。 

  • スキーマで現在サポートされている最大文字数は 100,000 文字である。
  • サポートされるメソッドは、GET、PATCH、PUT、POST、DELETE である。
  • プロパティに値が設定されている。
  • パラメータに名前が付けられている。
  • 対応付けと名前付きリストデータ型。
  • MIME タイプ application/json がサポートされている。
  • メディアタイプはサポートされていない。
  • OpenAPI 2.0 の有効な JSON スキーマ形式を使用している。
  • Apex の予約キーワードと同じ名前の文字列パラメータの使用は避ける。 

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

メモ

ヒント

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

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

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

リソース