最近のアクセス:
OpenAPI インポートツール

: GeneXus 17 Upgrade 6 以降では、OpenAPI 仕様のバージョン 2 とバージョン 3 の両方をサポートしています。OpenAPI インポーターは、スペックがバージョン 2 またはバージョン 3 のどちらを参照しているかを自動的に検出します。
OpenAPI インポートツールの主な目的は、任意の RESTful Web サービス (GeneXus によって生成できるかどうかを問わない) の OpenAPI 仕様 (旧称 Swagger RESTful API ドキュメント仕様) をインポートすることです。
OpenAPI インポートツールを使用する際は、RESTful サービスの利用に必要な一部のオブジェクト (プロシージャー構造化データタイプドメイン) はナレッジベースにインポートされます。

このツールを使用する利点は、各種操作、Web サービスを利用するために必要なメソッド、入出力パラメーター (サービスと応答を呼び出すための HTTP 本文構造) など、さまざまな情報を Swagger UI ドキュメントから取得する労力を省けることです。
このツールにアクセスするには、 [ ツール ] -> [ アプリケーションの統合 ] -> [ OpenAPI インポート ] メニューオプションを選択します。
イメージ:37611.png

OpenAPI インポートツールのダイアログ

イメージ:54380.png
ファイルパス/URL: RESTful サービスのドキュメントの URL またはファイルパスを Swagger 形式で入力します。
Swagger 形式: Swagger の仕様に沿って RESTful API を記述したファイルは、JSON オブジェクトとして表され、JSON 標準に準拠します。JSON のスーパーセットである YAML を使用して、Swagger 仕様ファイルを表すこともできます。
GeneXus の REST Web サービスでは、 [ Generate OpenAPI interface ] プロパティを有効にすると Swagger ファイルを取得できます。
モジュール/フォルダ: 自動的に生成されたオブジェクトの格納先として使用されます。
注: ナレッジベースのモジュール化を維持し、オブジェクトに対する不適切な変更を回避するため、YAML ファイルから自動的に作成されたオブジェクトの格納先モジュールを選択することを強くお勧めします。
たとえば、「Customers」という名前の構造が YAML ファイルに含まれている場合、この YAML をインポートしたときに「Customers」SDT が作成されます。ナレッジベースに「Customers」という名前の SDT が既に存在する場合は変更されます (YAML ファイルに含まれている構造に置き換えられます)。インポートされたオブジェクトがモジュール (CRM など) に作成される場合、SDT は「CRM.Customers」として作成され、既存のものを置き換えることはありません。

OpenAPI インポートツールの使用結果

このツールを使用すると、RESTful サービスを利用するために必要な一部のオブジェクト (プロシージャー、SDT、ドメイン) が KB にインポートされます。
KB にインポートされるオブジェクトの概要を次に示します:
オブジェクト フォルダ/モジュール 目的
ApiResponse SDT OpenAPICommon HTTP 応答構造を定義します。
CallApi プロシージャー OpenAPICommonP パラメーター化されたプロシージャーです。サービス URL と呼び出しのパラメーターを渡すと、HTTP メソッドを実行し、HTTP の結果を返します。
VarCharToJsonFormat、
DateTimeToJsonFormat、
DateToJsonFormat、
NumericToJsonFormat
OpenAPICommon 補助的なプロシージャーです。
AuthREADME (*) OpenAPICommon OAuth 2.0/OPenID Connect のフローに関してインポートされた仕様から取得される情報を表示するプロシージャーです。
ProcessServer (*) OpenAPICommon OpenAPI 3.0 ではサーバーのテンプレート化が許可されているため、このプロシージャーは、BaseURL の「Api」フォルダの下にあるプロシージャーを (&ServerUrlTemplatingVar パラメーターを使用して) 呼び出すときにユーザーが指定する値の置き換えに対処します。
ApiBaseUrl <MyModule>\Client RESTful サービスの呼び出しに使用される BaseURL を返します。ただし、ほとんどの場合、変更が必要です。

OpenAPI 3.0 仕様がインポートされるとき、このプロシージャーはその仕様に存在するすべてのサーバーを表示し、1 つのサーバー (最初のサーバー) のみをコメント解除します。
RESTful サービスのクライアントプロシージャー <MyModule>\Api サービスを呼び出すためのプロシージャーです。このプロシージャーの名前は、サービスのドキュメントファイル (Swagger) に含まれる operationId* に基づいて選択されます。

*operationId: 操作を識別するために使用される一意の文字列です。この ID は、API で記述されたすべての操作間で一意です。
サービスの入出力パラメーターを定義するために必要な SDT <MyModule>\Model サービスの入出力パラメーターです。
(*) バージョン 3 のインポート時にのみ生成されます。

この例では PetStore 仕様のインポートを示します。
: これは OpenAPI 3.0 仕様のインポートの例です。バージョン 2 の例は、以前のバージョンを参照してください。

KB エクスプローラーの構造の例

下の図は、例のプロシージャーに関連付けられている YAML ファイルをインポートした後の KB エクスプローラーの構造です。
イメージ:49285.png
コンシューマーのナレッジベースで OpenAPI インポートツールを使用して PetStore の Swagger ドキュメントを調査すると、PetStoreModule\Api パスに CreateUsersWithListInput というプロシージャーが自動的に生成されます。この例では、"PetStoreModule" がモジュールです。ツールで生成されたオブジェクトをインポートするように設定されています。
調査中のサービスに対応する Swagger ドキュメントの一部を次に示します。なお、RESTful サービスを利用するためのプロシージャーの名前は operationId の値に基づいて決定されます。
/user/createWithList: 
    post:
      tags:
        - user
      summary: Creates list of users with given input array
      description: Creates list of users with given input array
      operationId: createUsersWithListInput
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: successful operation
User は、RequestBody と Response の両方に対してツールによって自動的に生成される SDT です (この場合、タイプと一致するが、常に一致するとは限らない)。
次のパラメーター情報も Swagger ファイルから取得されます。
components: 
	schemas:
    ...
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: theUser
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: James
        email:
          type: string
          example: john@email.com
        password:
          type: string
          example: '12345'
        phone:
          type: string
          example: '12345'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: user

次の Parm ルールは、サービスを呼び出すためのスタブである CreateUsersWithListInput コンシューマーオブジェクトに生成されます。
parm(in:&ServerUrlTemplatingVar,  in:&body, out:&UserOUT, out:&HttpMessage, out:&IsSuccess);
&ServerUrlTemplatingVar パラメーターはすべてのコンシューマープロシージャーに存在します。これは「Properties」タイプの変数であり、BaseURL でテンプレート変数に値を割り当てる役割を持ちます。例えば、次の BaseURL があるとします:
{scheme}://{host}:8082/APIObjectPlayground.NETCoreEnvironment/rest
&ServerUrlTemplatingVar は次のように設定できます:
&ServerUrlTemplatingVar.Set("scheme","https") 

&ServerUrlTemplatingVar.Set("host","example")
その結果、BaseURL は次のようになります:
https://example:8082/APIObjectPlayground.NETCoreEnvironment/rest
このテンプレート化の値の割り当てを簡単にするために、割り当て可能な値の範囲を持つ列挙型ドメインを生成できます。例えば、これらのドメインの名前を「TemplateServer_{key_name}」とします。前述のケースで、「scheme」キーに対してドメインが生成された場合、その名前は「TemplateServer_scheme」になります。これは、仕様で列挙が指定されている場合にのみ行われます。
したがって、サービスを呼び出すために必要な作業は、CreateUsersWithListInput コンシューマーオブジェクトを呼び出すことです。そのためには、対応するパラメーターを渡して、結果を処理します:
PetStoreModule.CreateUsersWithListInput(&ServerUrlTemplatingVar,&User,&UserOUT,&HttpMessage,&IsSuccess) 
if &IsSuccess
     msg("Success!!") 
else
     msg("There was an error! ")     
endif 
msg("API return: " + &UserOUT.ToJson()) 
msg("HTTP Message " + &HttpMessage.Id + " " + &HttpMessage.Description)
&User は、以下のような構造を持ち、 [ Collection ] プロパティが True に設定されている Data Provider オブジェクトです。
User{
    id = 1000
    username = 'TheUser'
    firstName = 'Luis'
    lastName = 'Murillo'
    email = 'lmur@gmail.com'
    password = ''
    phone = '1234'
    userStatus = 1 
}
この方法は、入出力パラメーターを手動で定義し、HttpClient データタイプを使用して HTTP メソッドを実行する場合よりもはるかに簡単です。このタスクは、OpenAPI インポートツールによって実行され、必要なコードを自動的に生成します。

認証の追加

API へのセキュリティの追加が必要な場合もあります。これを行うには、CallApi プロシージャーのどこかに以下の行を追加する必要があります:
&httpClient.AddAuthentication(&authentication_method, "", &user, &password)
AddAuthentication メソッドが変数 &httpClient に適用されます。この変数は、HttpClient データタイプです。
変数 &authentication_method は数値である必要があります。0 から 3 の任意の値で希望するセキュリティ レベルを指定できます。さらに、変数 &user と &password を定義して、それぞれ値を割り当てる必要があります。この情報を以下のように直接追加することもできます:
&httpClient.AddAuthentication(0, "", "MyUser", "MyPassword")
値 "0" は認証タイプが標準であることを意味します。

参考情報

REST サービスとして公開されているビジネスコンポーネントを使用してデータを挿入する方法


サブページ
Created: 18/10/29 01:05 by Admin Last update: 24/12/18 01:21 by Admin
カテゴリ
Powered by GXwiki 3.0