ColorPalette RESTful API クライアント

この例では、Qt OpenAPI ジェネレータを使用して、colorpalette.yaml 仕様からRESTful APIクライアントコードを生成し、それをQMLアプリケーションに統合する方法を示します。その構造とUIは、「Qt Quick デモ - RESTful APIクライアント」の例とよく似ているため、ネットワーク通信や統合手法の違いを容易に確認できます。

例の動作確認

この例は、以下の手順で実行できます。

• Qt Creator

  「Welcome 」モードを開き、「Examples 」からこの例を選択します。詳細については、Qt Creator の「チュートリアル: ビルドと実行」を参照してください。

• Qt Extension for Visual Studio Code

  Command Palette から `Qt: Open Qt examples ` コマンドを実行し、リストからサンプルを選択します。詳細については、Qt Extension for Visual Studio Code: チュートリアル「ビルドと実行」を参照してください。

アプリケーションの機能

このサンプルは、「Qt Quick デモ - RESTful API クライアント」と同じ基本機能を提供します。

サーバーの選択

起動時、アプリケーションは、Color Paletteクライアントが通信できる事前定義済みのサーバーオプションを表示します：

• QtベースのREST APIサーバーの例（QtHttpServer

サーバーが選択され、「Connect 」ボタンが押されると、RESTful APIクライアントはテスト用のHTTP GETリクエストを発行し、サーバーが利用可能かどうかを確認します。サーバーが実行されていない場合、アプリケーションはサーバー選択画面のままになります。

OpenAPI仕様からのクライアントコード生成

CMakeLists.txt ファイルは、qt_add_openapi_client()関数を呼び出すことで、Qt OpenAPIジェネレータを起動し、colorpalette.yaml 仕様からクライアントコードを生成します。

qt_add_openapi_client(ColorpaletteClientExample
    SPEC_FILE
        ${CMAKE_CURRENT_SOURCE_DIR}/colorpalette.yaml
)

生成された API クラスColorsApi およびUsersApi は、低レベルの HTTP に関するすべての詳細を処理します:

• サーバーの設定
• すべての標準 HTTP メソッドに対する HTTP リクエストの構築
• 仕様に基づく入力パラメータのシリアライズ
• サーバー応答の型付きオブジェクトへの逆シリアライズ
• 成功およびエラーは Qt シグナルを通じて報告されます

QtNetworkAuth API を直接使用する別のバージョンのサンプルと比較して、このアプローチでは、ネットワークリクエストの手動での構築が不要になります。

生成されたAPIをQMLに公開する

生成された API クラス `ColorsApi ` および `UsersApi ` は、ApiBridges.h で定義されたヘルパークラスを介して QML に公開されます。各ヘルパーは `QML_FOREIGN ` マクロを使用し、基になる C++ インスタンスをシングルトンとして登録します。これにより、所有権は C++ に残ったまま、QML から同じオブジェクトにアクセスできるようになります。このトピックの詳細については、既存のオブジェクトをシングルトンとして公開する方法に関する Qt Qml ドキュメントを参照してください。

struct ForeignColorsAPI
{
    Q_GADGET
    QML_FOREIGN(QtOpenAPI::ColorsApi)
    QML_SINGLETON
    QML_NAMED_ELEMENT(ColorsApi)

};

QMLからのAPIの使用

登録が完了すると、APIはQML内でグローバルに利用可能になります。これにより、QMLコンポーネントは以下に示すように、ColorsApi やUsersApi に直接アクセスし、それらのメソッドを呼び出すことができます。

ColorsApi.getColors(page)

各APIメソッドは、操作が成功または失敗した際にシグナルを発信するため、QMLコンポーネントはサーバーからの応答を処理できます：

function onAddColorFinished() {
    root.fetchColors(root.currentColorPage)
}

function onAddColorErrorOccurred(errorType, errorStr) {
    root.handleError(errorStr)
}

ヘルパーシングルトン型

Credentials やColor など、一部のAPIメソッドは、パラメータとして複雑な型を受け取ります。この例では、ApiBridges.h 内でそのような型のインスタンスを構築するためのQMLシングルトンを提供しています：

class Credentials: public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON
public:
    Q_INVOKABLE QtOpenAPI::Credentials create(const QString &email, const QString &password)
    {
        QtOpenAPI::Credentials credentials;
        credentials.setEmail(email);
        credentials.setPassword(password);
        return credentials;
    }
};

これらのシングルトンは、APIメソッドを呼び出す際にQML内で使用できます。例えば、Credentials は、ログイン前に認証情報オブジェクトを作成するために使用されます：

let credentials = Credentials.create(userInfo.model.email, "apassword");
UsersApi.loginUser(credentials);

ソースファイル

code.qt.io上のサンプルプロジェクト