パブリック・サービス・レジストリへのパブリック REST API を使用したアクセス
パブリック REST API は、パブリック・サービス・レジストリへの読み取りアクセスを提供します。API は、ESB 経由で使用可能なサービスに関する情報を提供します。すべてのサービスに関する情報を返す REST 呼び出しを実行することも、指定の条件を満たすサービスに対してクエリを実行することもできます。呼び出しは、サービスに関する情報を JSON で返します。
ESB がどのように構成されているかによって、ユーザ名とパスワードを使用して、または匿名アクセスで API にアクセスできます。レジストリは、ユーザまたは匿名アクセスに付与された権限に基づいて、サービスを返します。サービス・レジストリ管理者は、ログイン情報に基づいてどのサービスが返されるかを制御します。例えば、管理者は、次のいずれかの方法でレジストリを構成できます。
-
匿名でログインしたユーザも含め、すべてのユーザにすべてのサービスに関する情報を返します。このポリシーでは、サービスに関する情報を取得できても、そのサービスを呼び出す権限があるわけではありません。
-
ログイン・アカウントまたは匿名アクセスに基づいて、ユーザが呼び出す権限を持つサービスのみに、返されるサービスを限定します。
各サービス・レジストリ・エントリには、以下の情報が含まれています。
-
サービスの ID。名前、ドメイン、およびバージョンで構成されます。
-
エンドポイント URL。サービスを呼び出すためのアドレスを提供します。通常、このアドレスは、ESB サーバ上にあります。サービスを実際に実行する外部サーバのエンドポイントは返されません。
-
サービスの呼び出しに使用するプロトコル。REST、SOAP、HTTP、TCP など。
-
サービスで使用される戻りのメカニズム。同期の戻りやコールバックなど。
-
説明。サービスの概要を示した簡単なテキストを提供します。
-
トピック。サービスの検索に使用されます。
-
スキーマ。スキーマ言語を使用しているメッセージについて返されるメッセージのスキーマ説明が含まれます。スキーマ情報には、スキーマ形式が含まれており、スキーマ定義の URL またはスキーマのコンテンツが提供されます。
-
アクションは、指定されたエンドポイントで使用可能な HTTP 要求メソッドを表します。それぞれのアクションは、サーバに対する要求メソッドの影響を表すことができ、受信メッセージおよび応答メッセージのスキーマを指定できます。
-
連絡先は、サービスの情報またはサポートを提供できるユーザまたは組織を表します。
-
属性は、レジストリ管理者が各サービスについて提供される情報を拡張するためのメカニズムを提供します。属性は、一連の、名前と値のペアで構成されます。
-
ファイルは、サービスに関する一連のファイルを提供するメカニズムを提供します。通常、これらはサービスを使用するための説明またはテンプレートの提供に使用されます。パブリック API がファイルに関する情報を返す場合、それにはファイルの内容は含まれていません。ファイルの内容はサイズがかなり大きい可能性があるためです。ファイルの内容にアクセスするには、明示的な要求を実行する必要があります。
サービス・レジストリ・パブリック API の概要
この節では、パブリック API での REST 呼び出しの概要を示します。各呼び出しの詳細は、"サービス・レジストリ・パブリック API リファレンス" を参照してください。
REST 呼び出し | URL および説明 |
---|---|
[取得] |
GET /about 実行可能なパブリック API REST 呼び出しが一覧表示されます。 |
[ID によるファイルの取得] |
GET /services/id/name/domain/version/file/filename 指定されたファイルが返されます。 |
[サービスの取得] |
GET /services ユーザがアクセス可能なすべてのサービスが表示されます。 |
[ID によるサービスの取得] |
GET /services/id/name/domain/version ユーザからアクセス可能で、指定された名前、ドメイン、およびバージョンに一致するサービスが返されます。 |
[プロトコルによるサービスの取得] |
GET /services/protocols/protocol-list ユーザからアクセス可能で、リスト内のいずれかのプロトコルに一致するすべてのサービスが表示されます。 |
[段階によるサービスの取得] |
GET /services/stages/stage-list ユーザからアクセス可能で、リスト内のいずれかの段階に一致するすべてのサービスが表示されます。 |
[バージョンによるサービスの取得] |
GET /services/version/version ユーザからアクセス可能で、指定されたバージョンに一致するすべてのサービスが表示されます。 |
[単語によるサービスの取得] |
GET /services/includesword/search-text ユーザからアクセス可能で、指定された検索テキストに一致するすべてのサービスが表示されます。 |
[変更以降のサービスの取得] |
GET /services/modifiedsince/date-time ユーザからアクセス可能で、指定された日時以降にレジストリ・エントリが作成されたか更新されているすべてのサービスが表示されます。 |
サービスの JSON 記述
サービスの取得呼び出しにより、共に返されるサービスの数に関係なく、1 つの JSON メッセージが返されます。サービスの取得要求に一致していて、さらにユーザからアクセス可能であるサービスがない場合、呼び出しは空の JSON メッセージを返します。それ以外の場合は、サービスの取得呼び出しにより、要求に一致し、ユーザからアクセス可能な 1 つ以上のサービスと共に JSON メッセージが返されます。この節では、返される JSON メッセージの例を示し、メッセージ内のフィールドについて説明します。
いずれのサービスの取得呼び出しによっても、次のようなメッセージが返されます。WSDL スキーマは、リスト内では省略形で示されていますが、JSON メッセージでは完全な形で表示されます。
[
{
"Name": "MathServiceSOAP",
"Domain": "UnitTest",
"Version": "1.1",
"Stage": "Live",
"Protocol": "SOAP",
"Description": "Add 2 Numbers",
"Endpoint": "https://jgm6457/enslatest/csp/support/Demo.SOAP.MathService.cls",
"ResponseStyle": "Sync",
"LastModified": "2022-03-16 19:07:47.469",
"Topics":
[
"Test",
"Maths"
],
"Contacts":
[
{
"Identity": "QD Developer Moon",
"Type": "Operator",
"Details": "Details of contact",
"BusinessPartner": "QD",
"Notes": "This SOAP service is designed to have minimum moving parts"
}
],
"Schema":
{
"Type": "Notes",
"Ref": "https://jgm6457/enslatest/csp/support/Demo.SOAP.MathService.cls?wsdl=1",
"Content": "<definitions targetNamespace='http://tempuri.org'> ...</definitions>",
"Notes": "Some WSDL"
},
"Public": true,
"Attributes":
[
{
"Name": "One",
"Value": "1"
}
],
"Files":
[
{
"Filename": "SOAPMathService.WSDL",
"FileExtention": ".WSDL",
"MIMEType": "text/text",
"CharEncoding": "UTF-8",
"FileSize": "1.44 KB",
"Contents": null
}
],
"Actions":
[
{
"Name": "Sum",
"Ref": "Sum",
"Verb": "POST",
"Description": "Add up 2 numbers",
"ReadOnly": false,
"Idempotent": true
}
]
},
{
"Name": "PublicREST",
"Domain": "UnitTest",
"Version": "0.9",
"Stage": "Live",
"Protocol": "REST",
"Description": "REST Call for the Public Registry",
"Endpoint": "http://mymachine.mynetwork.com:57774/csp/registry/docserver/public",
"ResponseStyle": "Sync",
"LastModified": "2022-03-05 16:15:33.38",
"Topics":
[
"Public",
"Search",
],
"Public": true,
"Attributes":
[
{
"Name": "Security",
"Value": "Username and Password"
}
],
"Files":
[
{
"Filename": "TestPlan",
"MIMEType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"CharEncoding": "UTF-8",
"FileSize": "16.95 KB",
"Contents": null
}
],
"Actions":
[
{
"Name": "public",
"Ref": "public",
"Verb": "GET",
"Description": "Returns REST endpoint for public registry",
"RequestSchema":
{
"Type": "Notes",
"Notes": "This is the REST endpoint to query the public Registry"
},
"ResponseSchema":
{
"Type": "REST Information
},
"ReadOnly": true,
"Idempotent": true
}
]
}
]
以下に、サービスの記述に含まれる可能性のあるフィールドのリストと説明を示します。すべてのフィールドについて、ESB サイトには、ESB のサービス・レジストリのフィールドの使用に関する情報を提供するガイドラインと一般的な使用方法が記載されているはずです。
[名前] は、サービスを特定します。サービスを特定するその他の属性は、[ドメイン] と [バージョン] です。[ドメイン] は通常、サービスのカテゴリを特定し、[バージョン] はバージョン番号を表す文字列です。[名前]、[ドメイン]、および [バージョン] の組み合わせは、サービス・レジストリ・エントリごとに固有です。例えば、ドメインが異なるか、バージョンが異なる限り、複数のサービスの名前が同じである可能性があります。
[ドメイン] は、サービスのカテゴリを指定します。
[バージョン] は、サービスのバージョンを特定します。
[ライフサイクルの段階] は、サービスの開発状態を表します。これは、以下のいずれかの値を持つことができます。[概念]、[開発]、[テスト]、[ステージング]、[稼働中]、[廃止]、および [非アクティブ]。
[サービス・プロトコル] は、クライアントがサービスへのアクセスに使用するプロトコルを表します。これは、以下のいずれかの値を持つことができます。[File]、[FTP]、[HL7]、[HTTP]、[REST]、[SOAP]、[SQL]、[X12]、および任意のカスタム値。
[説明] は、サービスの簡単な説明を提供します。
[エンドポイント] は、サービスの場所を指定します。これは、サービスの呼び出しに使用する場所です。
[応答スタイル] は、サービスが値を返す方法を表します。これは、以下のいずれかの値を持つことができます。[同期]、[コールバック]、[リモート・デポジット]、または空白の値。
レジストリ・エントリが ESB レジストリで前回変更された日時です。指定した日時以降に追加または更新されたサービスは、[変更以降のサービスの取得] を呼び出すことによって、検出できます。
[トピック] は、[単語によるサービスの取得] 呼び出しを使用してサービスを検索する場合に役立つ一連の用語を提供します。
[連絡先] は、サービスをサポートする、またはサービスに関連付けられているユーザまたは組織を指定します。[連絡先] には、以下のサブフィールドを含めることができます。
-
[ID] — そのユーザまたは組織の、名前またはその他の ID を指定します。
-
[タイプ] — 連絡先がサービスの [作成者]、[コンシューマ]、[プロバイダ]、[オペレータ]、[マネージャ]、[スポンサ] のいずれであるかを指定します。
-
[詳細] — そのユーザまたは組織の詳細を指定します。
-
[ビジネス・パートナー] — サービス・レジストリで内部的に使用されるフィールドですが、パブリック API を使用するアプリケーションには有用ではありません。
-
[備考] — そのユーザまたは組織に関する補足情報を指定します。
[スキーマ] は、サービス・メッセージの構造を表します。[スキーマ] には、構造の定義を表すサブフィールドや、構造の定義を含むサブフィールドが含まれます。[スキーマ] には、以下のサブフィールドを含めることができます。
-
[タイプ] — スキーマの記述に使用するスキーマ定義メカニズムの名前を指定します。これは、WSDL、XSD、HL7、SEF、X12、AST、EDF、またはカスタムのスキーマ定義メカニズムのいずれかです。
-
[リファレンス] — スキーマ定義の URL を指定します。
-
[コンテンツ] — スキーマ定義の完全なテキスト・コンテンツを表します。
-
[備考] — スキーマに関する補足情報を提供します。
-
[サムネイル] — スキーマの短い抜粋を提供します。
常に真の値を持ちます。サービス・レジストリで内部的に使用されます。
[属性] は、名前と値のペアのリストを指定します。名前と値のペアを使用することによって、ESB サービス・レジストリに、サービスに関する任意の情報を含めることができます。
[ファイル] は、レジストリ・エントリに 1 つ以上のファイルを含める方法を表します。例えば、1 つのファイルにサービスに関する説明を格納できます。1 つのレジストリ・エントリ内の各ファイルに一意のファイル名を付ける必要があります。いずれのサービスの取得呼び出しを実行した場合でも、返される JSON メッセージにはファイルの内容は含まれません。ファイルの内容を取得するには、別の GetFileByID 呼び出しを実行します。[ファイル] の各要素は、以下のサブフィールドから成ります。
-
[ファイル名] — ファイルの名前を表します。通常、これにはファイル拡張子が含まれます。1 つのレジストリ・エントリ内に、同じファイル名を持つファイルを 2 つ含めることはできません。
-
[ファイル拡張子] — ファイルの形式と目的に関する情報を提供します。オプション。
-
[MIME タイプ] — ファイルにアクセスするために使用するアプリケーションに関する情報を提供します。オプション。
-
[文字エンコード] — 文字エンコーディングに関する情報を提供します。オプション。
-
[ファイル・サイズ] — ファイル・サイズを表します。オプション。
-
[コンテンツ] — JSON サービス記述では、このフィールドは常に NULL です。ファイルの内容を取得するには、[ID によるファイルの取得] 呼び出しを実行する必要があります。
[アクション] は、指定した URL と共に使用できる SOAP アクションまたは REST HTTP 要求メソッドを指定します。SOAP アクションは、WSDL で定義されている情報の概要を提供します。[アクション] には、以下のサブフィールドを含めることができます。
-
[名前] — レジストリで対象のアクションの特定に使用する名前を指定します。
-
[リファレンス] — アクションの文字列識別子を指定します。
-
[動詞] — HTTP 要求メソッドを指定します。通常、これは GET、PUT、POST、または DELETE ですが、任意の HTTP 要求メソッドを指定できます。
-
[説明] — アクションのテキストによる説明を指定します。
-
[要求スキーマ] — 受信メッセージ本文の形式を指定します。以下のサブフィールドで構成されます。[タイプ]、[リファレンス]、[備考]、[サムネイル]、および [コンテンツ]。
-
[応答スキーマ] — 応答メッセージ本文の形式を指定します。以下のサブフィールドで構成されます。[タイプ]、[リファレンス]、[備考]、[サムネイル]、および [コンテンツ]。
-
[読み取り専用] — チェックを付けると、呼び出しによってサーバの状態は変更されないことが指定されます。
-
[べき等] — チェックを付けると、同じ呼び出しの複数回の実行が、1 回の呼び出しと同じ影響をサーバに与えることが指定されます。
[すべてのサービスの取得]
このサービスの取得 REST 呼び出しでは、表示する権限があるすべてのサービス・レジストリ・エントリが返されます。この呼び出しでは、ファイルの内容が省略されることを除いて、各サービスの完全なレジストリ・エントリが返されます。レジストリから、表示する権限があるすべてのサービスが返されます。この呼び出しの URL は次のとおりです。
GET /services
例えば、サーバと最上位ディレクトリを含む完全な URL は、次のようになります。
https://esb.example.com/registry/services
[ID によるサービスの取得]
[ID によるサービスの取得] 呼び出しは、識別されたサービスに関する情報を返します。サービスは、名前、ドメイン、およびバージョンで、一意に識別されます。この呼び出しの URL 構文は次のとおりです。
GET /services/id/name/domain/version
例えば、名前が coffeemaker、ドメインが demo、バージョンが 1.0 のサービスを取得するには、次の呼び出しを使用します。
https://esb.example.com/registry/services/id/coffeemaker/demo/1.0
[ID によるサービスの取得] は、指定したサービスについて、[すべてのサービスの取得] で返されるものと同じ情報を返します。そのため、[すべてのサービスの取得] を呼び出した場合、[ID によるサービスの取得] を呼び出す必要はありません。
この呼び出しの目的は、1 つのサービスを返すことですが、URL 内の名前、ドメイン、およびバージョンの部分にワイルドカードを指定できます。ワイルドカードを使用すると、この呼び出しは、指定の内容を満たすすべてのサービスを返します。
選択したサービスの取得
レジストリからすべてのサービスを取得したり、ID によって 1 つのサービスを取得したりする代わりに、サービスのサブセットを選択することができます。以下のいずれかの選択条件を指定できます。
-
[プロトコル] — リスト内のいずれかのプロトコルを使用するサービスを選択します。プロトコルとしては、以下のいずれかを指定できます。[File]、[FTP]、[HL7]、[HTTP]、[REST]、[SOAP]、[SQL]、[X12]、および任意のカスタム値。
-
[段階] — リストで指定した段階にあるサービスを選択します。段階としては、以下のいずれかを指定できます。[概念]、[開発]、[テスト]、[ステージング]、[稼働中]、[廃止]、および [非アクティブ]。
-
[バージョン] — 指定したバージョンのサービスを選択します。
-
[テキスト検索] — 以下のいずれかのフィールドの、指定したテキストを含むサービスを選択します。[名前]、[ドメイン]、[説明]、[エンドポイント]、および [トピック]。テキストの比較では、大文字小文字は区別されません。
-
[変更日] — 指定した日付以降にエントリが変更されているサービスを選択します。
[プロトコルによるサービスの取得] 呼び出しは、リスト内のいずれかのプロトコルに一致するプロトコルを使用するサービスを選択します。この呼び出しの URL 構文は次のとおりです。
GET /services/protocols/protocol-list
以下の呼び出しは、REST プロトコルを使用するすべてのサービスを返します。
https://esb.example.com/registry/services/protocols/REST
以下の呼び出しは、REST プロトコルと SOAP プロトコルのいずれかを使用するすべてのサービスを返します。
https://esb.example.com/registry/services/protocols/REST,SOAP
[段階によるサービスの取得] 呼び出しは、リスト内のいずれかの段階に一致する段階にあるサービスを選択します。この呼び出しの URL 構文は次のとおりです。
GET /services/stages/stage-list
以下の呼び出しは、稼働中の段階にあるすべてのサービスを返します。
https://esb.example.com/registry/services/stages/Live
[バージョンによるサービスの取得] 呼び出しは、指定したバージョンに一致するバージョンのサービスを選択します。この呼び出しの URL 構文は次のとおりです。
GET /services/version/version
例えば、以下の呼び出しは、バージョンが 1.0 のすべてのサービスを返します。
https://esb.example.com/registry/services/version/1.0
[単語によるサービスの取得] 呼び出しは、以下のいずれかのフィールドに、指定の検索テキストが含まれるすべてのサービスを検出します。
-
[名前]
-
[ドメイン]
-
[説明]
-
[エンドポイント]
-
[トピック]
[単語によるサービスの取得] 呼び出しの URL 構文は次のとおりです。
GET /services/includesword/search-text
例えば、以下の呼び出しは、いずれかのフィールドに “accounts, payable” というテキスト文字列が含まれるすべてのサービスを返します。
https://esb.example.com/registry/services/includesword/accounts,%20payable
[変更以降のサービスの取得] 呼び出しは、特定の日時以降にレジストリ・エントリが変更されているすべてのサービスを返します。この呼び出しの URL 構文は次のとおりです。
GET /services/modifiedsince/date-time
例えば、次の呼び出しは、特定の日時以降にエントリが変更されているすべてのサービスを返します。
https://esb.example.com/registry/services/modifiedsince/2015-02-1%2011:30
日付を年-月-日の形式で指定し、URL スペース・コードの %20 を区切り文字として使用し、時刻を24時間制で時間:分の形式で指定します。
ファイルの内容の取得
[ID によるファイルの取得] 呼び出しは、指定したファイルの内容を返します。テキスト・ファイルとバイナリ・ファイルのいずれかで返すことができます。JSON メッセージやファイル・メタデータを返すことはありません。ファイルの内容だけを返します。この呼び出しの URL 構文は次のとおりです。
GET /services/id/name/domain/version/file/filename
ここで、name/domain/version は、サービスを特定し、filename は、そのサービス内のファイルの名前を指定します。
例えば、以下の呼び出しは、ファイルの内容を返します。
https://esb.example.com/registry/services/id/coffeemaker/demo/1.0/file/HowToCallCoffeemaker.docx
[ID によるファイルの取得] ではワイルドカードを使用することはできません。URL 内の name/domain/version の各部分にワイルドカードを指定することはできますが、指定に一致するサービスが複数ある場合のこの呼び出しの動作は未定義です。