Класс EnginioClient

EnginioClient обрабатывает все взаимодействия с сервером Enginio Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

• 8 открытых функций унаследованных от EnginioClientConnection
• 31 открытых функций унаследованных от QObject

Сигналы

• 4 сигнала унаследованных от EnginioClientConnection
• 2 сигнала унаследованных от QObject

Дополнительные унаследованные члены

• 4 свойства унаследованные от EnginioClientConnection
• 1 свойство унаследованное от QObject
• 1 открытый слот унаследованный от QObject
• 11 статических открытых членов унаследованных от QObject
• 9 защищенных функций унаследованных от QObject

Подробное описание

EnginioClient обрабатывает все взаимодействия с сервером Enginio

Сервер Enginio поддерживает несколько отдельных «бекендов» для каждого аккаунта. Выбрав backendId, выбирается бекенд. После установки идентификатора возможны взаимодействия с сервером. Информация о бекенде доступна на панели управления Enginio после входа на Enginio.

EnginioClient *client = new EnginioClient(parent);
client->setBackendId(QByteArrayLiteral("YOUR_BACKEND_ID"));

Основные функции для взаимодействия с бекендом — create(), query(), remove() и update(). Возможен полнотекстовый поиск на сервере с помощью fullTextSearch(). Для работы с файлами предоставляются downloadUrl() и uploadFile(). Функции асинхронные, что означает, что они не блокируют выполнение и результат будет доставлен вместе с сигналом EnginioReply::finished().

Примечание: После завершения запроса пользователь обязан удалить объект EnginioReply в соответствующее время. Не удаляйте его напрямую внутри слота, подключенного к finished(). Используйте функцию deleteLater().

Для удобства работы с запросами, возвращающими массив данных, предоставляется модель EnginioModel.

Документация по членам-функциям

EnginioClient::EnginioClient(QObject *parent = Q_NULLPTR)

Создаёт новый объект EnginioClient с parent как родителем QObject.

EnginioClient::~EnginioClient()

Удаляет объект EnginioClient.

Это завершает сеанс Enginio.

EnginioReply *EnginioClient::create(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Вставляет новый object в базу данных.

Возвращаемый EnginioReply указывает на успех создания объекта. Объект становится доступным на бекенде, если завершился без ошибок.

operation определяет тип создаваемого объекта. Например, обычный объект, пользователь или группа пользователей. По умолчанию используется Enginio::ObjectOperation для создания обычных объектов.

Примечание: для обычных объектов требуется objectType, и оно должно начинаться с "objects.".

JSON для создаваемого объекта должен иметь следующую структуру:

{
    "objectType": "object.myType",
    "name" : "A thing",
    "price" : "5",
}

Где требуется только свойство objectType, а name и price — примеры пользовательских свойств.

Пользователи и другие типы объектов создаются аналогичным образом, но не требуют objectType.

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
query["title"] = QString::fromUtf8("A todo");
query["completed"] = true;
const EnginioReply* response = client.create(query);

Для добавления нового члена в группу пользователей JSON должен выглядеть так:

{
    "id": "groupId",
    "member": { "id": "userId", "objectType": "users" }
}

Он может быть создан так:

QJsonObject query;
query["id"] = groupId;
QJsonObject user;
user["id"] = userId;
user["objectType"] = QString::fromUtf8("users");
query["member"] = user;

EnginioReply *reply = client.create(query, Enginio::UsergroupMembersOperation);

Возвращает EnginioReply со статусом и данными после завершения.

См. также EnginioReply, query(), update(), remove() и Enginio::Operation.

EnginioReply *EnginioClient::downloadUrl(const QJsonObject &object)

Получает временную ссылку на файл, хранящийся в Enginio.

По этой ссылке можно загрузить файл. Ссылка действительна определённое время, указанное в ответе.

QJsonObject object;
object["id"] = fileId; // ID of an existing object with attached file

const EnginioReply *replyDownload = _client.downloadUrl(object);

Имя свойства может быть любым, но должно совпадать с тем, которое использовалось при загрузке файла. Таким образом, к одному объекту можно прикрепить несколько файлов (по одному на имя свойства).

Если файл имеет несколько вариантов, можно запросить вариант, включив его в object.

{
    "id": "abc123",
    "variant": "thumbnail"
}

void EnginioClient::error(EnginioReply *reply)

Этот сигнал испускается, когда запрос к бекенду возвращает ошибку.

reply содержит подробности возникшей ошибки.

См. также EnginioReply.

void EnginioClient::finished(EnginioReply *reply)

Этот сигнал испускается, когда запрос к бекенду завершается.

reply содержит возвращённые данные. Этот сигнал испускается как для успешных, так и для неудачных запросов.

С этого момента владение reply переходит от EnginioClient, поэтому разработчик несет ответственность за удаление reply после обработки этого сигнала. Этого можно достичь, вызвав метод deleteLater() для reply.

См. также EnginioReply.

EnginioReply *EnginioClient::fullTextSearch(const QJsonObject &query)

Полнотекстовый поиск на бекенде Enginio

query — JSON, отправленный на бекенд для выполнения полнотекстового поиска. Обратите внимание, что для поиска необходимо, чтобы искомые свойства были индексированы (на сервере, настраивается в бекенде).

Возвращает EnginioReply содержащий статус и результат, как только он завершится.

См. также EnginioReply, create(), query(), update(), remove(), Пример адресной книги и Структура JSON-запроса.

EnginioReply *EnginioClient::query(const QJsonObject &query, const Enginio::Operation operation = Enginio::ObjectOperation)

Запрос к базе данных

query — это объект, содержащий фактический запрос к бэкенду. Запрос будет выполнен для части operation бэкенда.

query должен содержать «objectType», который должен указывать на тип, определённый в бэкенде. Также он может содержать:

• query — описывает, как запросы к объектам, позволяет фильтровать результаты. См. {https://engin.io/documentation/rest/parameters/queries} {Структура JSON-запроса}
• limit — ограничивает количество объектов, которое сервер должен вернуть (значение по умолчанию — 100).
• offset — количество объектов, которые сервер должен пропустить с начала возвращаемых результатов. Обратите внимание, что сервер хранит данные в случайном порядке, поэтому использование offset подразумевает использование sort также.
• sort — описывает, как сортировать результаты. См. Структуру JSON-запроса для сортировки
• count — если count установлено, сервер вернёт только количество совпадающих объектов
• include — описывает, какие другие объекты включаются в ответ. См. Структуру JSON-включения

JSON для перечисления всех объектов типа «objects.image»:

{
    "objectType": "objects.image"
}

Пример использования include для получения file ссылок и параметром запроса, ограничивающим результаты только теми объектами, где ссылка действительна:

{
    "objectType": "objects.image",
    "include": {"file": {}},
    "query" : { "file": { "$ne": null } }
}

Для запроса к базе данных всех объектов типа «objects.todo»:

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
EnginioReply *reply = client.query(query);

Возвращает EnginioReply, содержащий статус и результат, как только он завершится.

См. также EnginioReply, create(), update() и remove().

EnginioReply *EnginioClient::remove(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Удаление объекта из базы данных.

Объект object, который необходимо удалить, идентифицируется по его идентификатору объекта и, если это обычный объект, также objectType.

JSON, идентифицирующий объект, выглядит следующим образом:

{
    "objectType": "objects.images",
    "id": "52b1a94b5a3d8b15b1037ff5"
}

operation — область, из которой объект удаляется. По умолчанию он равен Enginio::ObjectOperation для удаления обычных объектов по умолчанию.

Для удаления объекта todo:

QJsonObject query;
query["objectType"] = QString::fromUtf8("objects.todos");
query["id"] = objectId;
const EnginioReply *response = client.remove(query);

Возвращает EnginioReply, содержащий статус и данные по завершении.

См. также EnginioReply, create(), query() и update().

[signal] void EnginioClient::sessionAuthenticated(EnginioReply *reply) const

Вызывается при успешном входе пользователя.

Сигнал вызывается после успешного входа пользователя в бэкенд. С этого момента все взаимодействия с бэкендом будут использовать эти учетные данные. reply содержит информацию о входе и пользователе. Детали могут отличаться в зависимости от используемого метода аутентификации, но типичный ответ выглядит следующим образом:

{
  "access_token": "...",              // oauth2 access token
  "refresh_token": "...",             // oauth2 refresh token
  "token_type": "bearer",             // oauth2 token type
  "expires_in": 28799,                // oautth2 token expiry date
  "enginio_data": {
    "user": {
      "id": "...",                    // this user Id
      "createdAt": "...",             // when the user was created
      "creator": {                    // who created the user
        "id": "creatorId",
        "objectType": "users"
      },
      "email": "user@user.com",       // the user's email address
      "firstName": "John",            // the user's first name
      "lastName": "Foo",              // the user's last name
      "objectType": "users",
      "updatedAt": "2013-11-25T14:54:58.957Z",
      "username": "JohnFoo"           // the user's login
    },
    "usergroups": []                  // usergroups to which the user belongs
  }
}

Примечание: reply будет автоматически удалён после этого сигнала, поэтому его нельзя сохранять.

См. также sessionAuthenticationError(), EnginioReply и EnginioOAuth2Authentication.

[signal] void EnginioClient::sessionAuthenticationError(EnginioReply *reply) const

Вызывается при неудачном входе пользователя.

reply содержит детали о причинах неудачи входа.

Примечание: reply будет автоматически удалён после этого сигнала, поэтому его нельзя сохранять.

См. также sessionAuthenticated(), EnginioReply, EnginioClientConnection::identity() и EnginioOAuth2Authentication.

[signal] void EnginioClient::sessionTerminated() const

Вызывается при выходе пользователя.

См. также EnginioClientConnection::identity() и EnginioOAuth2Authentication.

EnginioReply *EnginioClient::update(const QJsonObject &object, const Enginio::Operation operation = Enginio::ObjectOperation)

Обновление объекта в базе данных.

operation — область, в которой объект object обновляется. По умолчанию — Enginio::ObjectOperation для обновления обычных объектов.

Для изменения свойства «name» объекта на «Новое имя» используйте следующий JSON:

{
    "id": "objectId",
    "objectType": "objects.objectType",
    "name": "New Name"
}

Все другие существующие свойства объекта не затрагиваются обновлением.

Для обновления списка управления доступом к объекту используйте следующий JSON:

{
    "id": "objectId",
    "objectType": "objects.objectType",
    "access": { "read": ["id": "userId", "objectTypes": "users"],
                "update": ["id": "userId", "objectTypes": "users"],
                "admin": ["id": "userId", "objectTypes": "users"] }
}

В C++, обновление списка управления доступом можно выполнить так:

QJsonObject aclUpdate;
aclUpdate["objectType"] = obj["objectType"];
aclUpdate["id"] = obj["id"];
QString json = "{ \"read\": [ { \"id\": \"%3\", \"objectType\": \"users\" } ],"
                 "\"update\": [ { \"id\": \"%2\", \"objectType\": \"users\" } ],"
                 "\"admin\": [ { \"id\": \"%1\", \"objectType\": \"users\" } ] }";
json = json.arg(id1, id2, id3);
aclUpdate["access"] = QJsonDocument::fromJson(json.toUtf8()).object();

reqId = client.update(aclUpdate, Enginio::AccessControlOperation);

Возвращает EnginioReply содержащий статус запроса и данные по завершении.

См. также EnginioReply, create(), query() и remove().

EnginioReply *EnginioClient::uploadFile(const QJsonObject &object, const QUrl &file)

Сохраняет file, прикреплённую к object, в Enginio

Каждый загружаемый файл должен быть связан с объектом в базе данных.

Примечание: Загрузка будет работать только с должным серверным конфигурированием: в панели управления создайте свойство нужного типа. Установите это свойство в ссылку на файлы.

Каждый загружаемый файл должен быть связан с объектом в базе данных.

Для загрузки файла сначала создайте объект:

QJsonObject obj;
obj["objectType"] = QString::fromUtf8("objects.FilesFileUploadDownload");
const EnginioReply* createReply = _client.create(obj);

Затем выполните фактическую загрузку:

QJsonObject object;
object["id"] = _id;
object["objectType"] = QString::fromUtf8("objects.FilesFileUploadDownload");
object["propertyName"] = QStringLiteral("fileAttachment");

QJsonObject fileObject;
fileObject[QStringLiteral("fileName")] = fileName;

QJsonObject uploadJson;
uploadJson[QStringLiteral("targetFileProperty")] = object;
uploadJson[QStringLiteral("file")] = fileObject;
const EnginioReply *responseUpload = _client.uploadFile(uploadJson, QUrl(filePath));

Примечание: Нет необходимости в непосредственном удалении файлов. Вместо этого, при удалении объекта, содержащего ссылку на файл, файл будет удалён автоматически.

См. также downloadUrl().