Взаимодействие с Saures API.

Давненько вынашиваю идею поиграться с последней версией .net framework’а и Docker’ом. И так удачно совпало, что есть у меня задача при решении которой я получу практическую пользу. Речь идёт о передаче показаний счётчиков воды из облака Saures в Томский расчётный центр. Немного контекста: Saures — это Российская компания занимающаяся автоматизацией учёта и контроля коммунальных ресурсов. Каталог оборудования компании позволяет организовать очень интересные сценарии. В простейшем случае для учёта потребления воды понадобятся счётчики и контроллер. Контроллер передаёт показания подключенных к нему устройств в «облако» Saures. Доступ к этим данным можно получить в том числе и через API. Именно это я и буду делать в данной статье.

Итак, первым делом я создал решение WaterMeterAutomation и проект библиотеки SauresApi. Для упрощения «общения» с REST API и JSON буду использовать совершенно замечательную библиотеку Flurl. Если быть точнее то Flurl состоит из двух NuGet пакетов: непосредственно Flurl позволяет «строить» (собирать..?) URL, в то время как Flurl.Http — это HTTP-клиент с поддержкой сериализации/десериализации Json. Вот как выглядела первая версия метода LoginAsync в классе Api для вызова метода login API Saures:

public async Task<string> LoginAsync(string email, string password)
{
    var result = await _rootUrl.AppendPathSegment("login")
        .PostUrlEncodedAsync(new {email, password})
        .ReceiveString();
        
    return result;
}

Коротко и наглядно!
Чтобы запустить этот код добавлю в решение XUnit проект интеграционных тестов SauresApi.IntegrationTests. Класс TestApi помечу атрибутом [Trait("Category", "IntegrationTests")], предварительно добавив категорию «IntegrationTests» в настройки Resharper’а Options -> Unit Testing -> General -> Skip tests from categories. Это позволит не запускать интеграционные тесты во время запуска всех тестов решения, поскольку конкретно эти тесты мне нужны как средство отладки во время разработки клиента API и не более.
Код теста максимально прост:

[Fact]
public async Task TestLogin()
{
    var api = await _api.LoginAsync(_suaresApiLogin, _suaresApiPassword);
    api.Should().NotBeNullOrEmpty();
}

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

{
    "data": {
        "api": 1,
        "role": 1,
        "sid": "92104027-908a-43dd-b18b-b06b918f696d"
    },
    "errors": [],
    "status": "ok"
}

Признаюсь честно: первую объектную обёртку для этого JSON я накидал ручками, но позже вспомнил, что где-то на просторах интернета видел средство создания классов на основе JSON. Первая же ссылка в Google привела на https://json2csharp.com. В дальнейшем все классы я генерировал на этом сайте и затем менял названия.
Далее поковырявшись в документации Saures API пришёл к выводу, что моя конечная цель это метод /object/meters — именно он возвращает список всех измерительных приборов подключенных к контроллеру с их идентификаторами и показаниями. Но для вызова требуется такой параметр как идентификатор объекта, получить который можно вызвав метод /user/objects. Реализация двух вышеупомянутых методов была аналогична методу login и в конечном итоге класс Api стал выглядеть следующим образом:

public class Api
{
    private readonly Url _rootUrl;

    public Api(string host)
    {
        _rootUrl = host.AppendPathSegment("1.0");
    }

    public async Task<string> LoginAsync(string email, string password)
    {
        var result = await _rootUrl.AppendPathSegment("login")
            .PostUrlEncodedAsync(new {email, password})
            .ReceiveJson<Result<LoginData>>();

        result.ThrowExceptionIfAny();

        return result.data.sid;
    }

    public async Task<UserObject> GetUserObjects(string sid)
    {
        var result = await _rootUrl.AppendPathSegment("user").AppendPathSegment("objects")
            .SetQueryParam("sid", sid)
            .GetJsonAsync<Result<UserObjectsData>>();

        result.ThrowExceptionIfAny();

        return result.data.objects[0];
    }

    public async Task<Sensor> GetObjectMeters(string sid, int id)
    {
        var result = await _rootUrl.AppendPathSegment("object").AppendPathSegment("meters")
            .SetQueryParam("sid", sid)
            .SetQueryParam("id", id)
            .GetJsonAsync<Result<SensorsData>>();

        result.ThrowExceptionIfAny();

        return result.data.sensors[0];
    }
}

Метод ThrowExceptionIfAny бросает ApplicationException если массив errors в результирующем JSON не пустой.
Хранение имени пользователя и пароля в тестовом проекте организовал через переменные окружения (Environment variables). Это позволит использовать эти данные только на моей машине и в то же время они не засветятся в открытом виде в Git или другой системе управления версиями. В будущем этот же подход планирую использовать в главном приложении с поддержкой Docker’а. Финальная версия тестового класса:

[Trait("Category", "IntegrationTests")]
public class TestApi
{
    private readonly Api _api;
    private readonly string _suaresApiLogin;
    private readonly string _suaresApiPassword;

    private const string Sid = "0af2b792-2cf9-420c-987e-74e4909c815e";
    private const int Id = 12345;

    public TestApi()
    {
        _suaresApiLogin = Environment.GetEnvironmentVariable("SauresApiLogin", EnvironmentVariableTarget.Process);
        _suaresApiPassword = Environment.GetEnvironmentVariable("SauresApiPassword", EnvironmentVariableTarget.Process);
        _api = new Api("https://api.saures.ru");
    }

    [Fact]
    public async Task TestLogin()
    {
        var api = await _api.LoginAsync(_suaresApiLogin, _suaresApiPassword);
        api.Should().NotBeNullOrEmpty();
    }

    [Fact]
    public async Task TestUserObjects()
    {
        var result = await _api.GetUserObjects(Sid);
        result.id.Should().BeGreaterThan(0);
    }

    [Fact]
    public async Task TestGetObjectMeters()
    {
        var result = await _api.GetObjectMeters(Sid, Id);
        result.meters.Should().HaveCount(4);
    }
}

Sid — идентификатор сессии получаемый при вызове Login. Id — идентификатор моего объекта, который вроде бы как постоянен, т.е. метод GetUserObjects можно вызвать единожды.

Отдельно хочу упомянуть про метод Should() в тестах — он принадлежит ещё одному замечательному инструменту Fluent Assertions, который позволяет сделать утверждения в модульных и интеграционных тестах максимально простыми и удобочитаемыми, но в то же время эффективными. Возможно в будущем я остановлюсь на этой теме подробней, поскольку в данном случае потенциала Fluent Assertions попросту не видно.

P.S. в этой статье впервые я использую подсветку синтаксиса кода. Хочу поблагодарить за это Vicky Agravat за разработку дополнения CodeMirror Blocks.