ColorPalette RESTful APIクライアント

この例では、Qt OpenAPI ジェネレータを使って、colorpalette.yaml 仕様から RESTful API クライアントコードを生成し、QML アプリケーションに統合する方法を示します。その構成と UI は、Qt Quick Demo - RESTful API clientexample と密接に一致しているので、ネットワーキングと統合アプローチの違いを簡単に識別することができます。

例の実行

からサンプルを実行するには Qt Creatorからサンプルを実行するには、Welcome モードを開き、Examples からサンプルを選択します。詳細については、Qt Creator:Tutorialを参照してください：ビルドと実行。

アプリケーションの機能

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

サーバーの選択

起動時に、Color Paletteクライアントが通信可能な、定義済みのサーバーオプションを提示します：

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

サーバーを選択し、Connect ボタンを押すと、RESTful API クライアントはテスト HTTP GET リクエストを発行し、サーバーが利用可能であることを確認します。サーバーが実行されていない場合、アプリケーションはサーバー選択ビューに留まります。

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

CMakeLists.txt ファイルは Qt OpenAPI ジェネレーターを起動し、qt6_add_openapi_client関数を呼び出して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++ のインスタンスをシングルトンとして登録します。このトピックの詳細については、Qt QML documentation onexposing an existing object as a singleton を参照してください。

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)
}

ヘルパーのシングルトン型

APIメソッドの中には、Credentials やColor のように、自明でない型をパラメータとして受け取るものがあります。この例では、そのような型のインスタンスを構築するためのQMLシングルトンをApiBridges.h に用意しています：

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