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

이러한 싱글톤은 QML에서 API 메서드를 호출할 때 사용할 수 있습니다. 예를 들어, Credentials 은 로그인 전에 자격 증명 객체를 생성하는 데 사용됩니다:

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

소스 파일

code.qt.io의 예제 프로젝트