Сервис "Реестр ключей"¶

Используйте метод PostRecord для добавления или изменения записи о RFID-ключе в реестре ключей:

• Добавление нового RFID-ключа --- запрос отправляется с уникальным 14-битовым номером ключа uid, но без id-идентификатора ключа. В этом случае сервер создаст уникальный id и добавит новую запись в реестр.
• Обновление RFID-ключа --- в запросе и в реестре ключей присутствует id ключа. В этом случае обновляются только изменённые атрибуты RFID-ключа в реестре.

uid --- это уникальный номер ключа, который вендор присваивает RFID-ключу у себя на производстве. Формат: 14 бит. Указывается при создании нового RFID-ключа в реестре.

id --- это номер RFID-ключа в реестре на сервере. Тип строка 7 байт в формате GUID. Генерируется сервером при добавлении нового RFID-ключа в реестр, а в дальнейшем используется для обращения к ключу в запросах методов реестра.

После авторизации вы (как производитель) можете изменять только свои ключи, которые вы уже добавляли в реестр с этой же учётной записью.

• Запрос --- PostRecordRequest

• Ответ --- PostRecordResponse

В качестве тела запроса передаётся JSON-объект с атрибутами нового/обновляемого RFID-ключа, которые помещаются в соответствующую запись в реестре ключей.

Параметры запроса:

Примеры запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

using System.Text.Json;
using Google.Protobuf.WellKnownTypes;
using Grpc.Core;
using Grpc.Net.Client;
using IdentityModel.Client;
using Keyapis.Rfidregistry.V1;

// Формируем gRPC-канал
var credentials = CallCredentials.FromInterceptor((_, metadata) =>
{
    metadata.Add("Authorization", $"Bearer {token}");
    return Task.CompletedTask;
});

using var channel = GrpcChannel.ForAddress(
    // https://openapi-key.deploy.rtkit.dev/keyapis_rfidregistry_v1/
    "https://rfid-registry-staging.k8s.key.rt.ru:443",
    new GrpcChannelOptions
    {
        Credentials = ChannelCredentials.Create(new SslCredentials(), credentials)
    }
);

// Подключаем gRPC-клиент к созданному каналу

var client = new RecordService.RecordServiceClient(channel);

// Для примера cгенерируем uid для RFID-ключа в формате строки 7 байт.
var buffer = new byte[7];
new Random().NextBytes(buffer);
var uid = string.Join(string.Empty, buffer.Select(b => b.ToString("x2").ToUpper()));

// Запрос PostRecord в асинхронном режиме
var postRecordResponse = await client.PostRecordAsync(new PostRecordRequest
{
    Data = new Record
    {
        RfidType = Record.Types.RfidType.Fob,
        EncryptionType = Record.Types.EncryptionType.Sl0,
        Uid = uid,
        StatusType = Record.Types.StatusType.Shipped,
        OrderNumber = "openapi-key-csharp-example",
        OrderAt = DateTime.UtcNow.ToTimestamp()
    }
});

Console.WriteLine($"PostRecordResponse response: {postRecordResponse}\n");

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

RECORD_UID=$(openssl rand -hex 7 | tr a-z A-Z)
RECORD_ORDER_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
grpcurl -d @ -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService.PostRecord <<EOM
{
"record": {
    "rfid_type": "FOB",
    "encryption_type": "SL0",
    "uid": "${RECORD_UID}",
    "status_type": "SHIPPED",
    "order_number": "openapi-key-example",
    "order_at": "${RECORD_ORDER_AT}"
}
}
EOM

В ответе возвращается JSON-объект с данными добавленного/обновлённого RFID-ключа или код ошибки в случае некорректного запроса.

Среди атрибутов созданного ключа теперь присутствует идентификатор id (тип GUID), сгенерированный сервером. Используйте его в дальнейшем для обращения к данному RFID-ключу при запросах в реестр ключей.

sequenceDiagram

    autonumber

    participant c as Клиент
    participant rr as Реестр ключей

        c ->> rr: Запрос PostRecordRequest на добавление RFID-ключа
        rr ->> rr: Проверка атрибутов
    alt Атрибуты OK
        %%rect rgb(191, 255, 223)
            rr ->> c: Ответ PostRecordResponse
        %%end
    else Ошибка в атрибутах
        %%rect rgb(255, 223, 223)
            rr ->> c: Ответ gRPC "Error" в случае ошибки
        %%end
    end

sequenceDiagram

    autonumber

    participant c as Клиент
    participant rr as Реестр ключей

    c ->> rr:  Запрос PostRecordRequest на обновление RFID-ключа
    rr ->> rr: Проверка атрибутов
    alt Аттрибуты OK
        rr ->> rr:  Изменение атрибутов RFID-ключа
        %%rect rgb(191, 255, 223)
            rr ->> c: Ответ GRPC PostRecordResponse
        %%end
    else
        %%rect rgb(255, 223, 223)
            rr ->> c: Ответ GRPC PostRecordResponse в случае ошибки
        %%end
    end

Метод GetRecord позволяет получать информацию о RFID-ключе из реестра ключей. В ответе содержится объект в формате JSON с полями данных и атрибутами записи в реестре.

Вы можете получать данные только для своих ключей, которые вы ранее уже добавили в реестр ключей под своей учётной записью с токеном доступа.

• Запрос --- GetRecordRequest

• Ответ --- GetRecordResponse

Параметры запроса:

В качестве параметра запроса передаётся id-индентификатор ключа в формате строки 7 байт, тип Guid.

Примеры запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

using System.Text.Json;
using Google.Protobuf.WellKnownTypes;
using Grpc.Core;
using Grpc.Net.Client;
using IdentityModel.Client;
using Keyapis.Rfidregistry.V1;

// Record id
var id = "12345678-9ABC-DEF0-0000-000000000000";

var getRecordResponse = await client.GetRecordAsync(new GetRecordRequest
{
    Id = id
});

Console.WriteLine($"GetRecordResponse response: {getRecordResponse}\n");

1
2
3
4
5
6
7

ACCESS_TOKEN="ваш_токен"
RECORD_ID=$(openssl rand -hex 7 | tr a-z A-Z)
grpcurl -d @ -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService.GetRecord <<EOM
{
"id": "${RECORD_ID}"
}
EOM

Метод GetRecordList позволяет получить заданный список RFID-ключей. Вы можете использовать полученные данные для постраничного вывода на экран, в файл или иное средство вывода.

В запросе необходимо указать параметры фильтра и постраничного вывода (пагинации). Ответ возвращается в формате потокового (стримингового) сообщения и содержит перечень RFID-ключей для постраничного вывода. Записи извлекаются из реестра, начиная с текущей позиции курсора.

В ответе возвращаются только те записи RFID-ключей, которые вы ранее сохранили в реестр ключей под своей учётной записью с токеном доступа.

• Запрос --- GetRecordListRequest

• Ответ --- GetRecordListResponse

Параметры запроса:

В случае запроса без параметров сервис вернёт ответ со списком RFID-ключей, отобранных с настройкой фильтрации и сортировки по умолчанию --- самые новые 20 записей по дате добавления в реестр.

Примеры запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

using System.Text.Json;
using Google.Protobuf.WellKnownTypes;
using Grpc.Core;
using Grpc.Net.Client;
using IdentityModel.Client;
using Keyapis.Rfidregistry.V1;

// Record uid
var uid = "1234567ABCDEF0";

var getRecordListResponse = client.GetRecordList(new GetRecordListRequest
{
    Filter = new RecordFilter
    {
        Uids = { uid }
    }
});

Console.WriteLine($"getRecordListResponse response:");

await foreach (var record in getRecordListResponse.ResponseStream.ReadAllAsync())
{
    Console.WriteLine($"    {record}");
}

Console.WriteLine();

1
2

ACCESS_TOKEN="ваш_токен"
grpcurl -d @ -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService.GetRecordList

В ответе на запрос списка RFID-ключей сервер возвращает перечень отфильтрованных записей в реестре ключей или код ошибки в случае некорректного запроса.

Используйте метод GetRecordCount, чтобы узнать общее количество доступных вам RFID-ключей в реестре с учётом заданного фильтра. Суммарное значение будет соответствовать только тем RFID-ключам, которые вы ранее сохраняли в реестр ключей под своей учётной записью с токеном доступа.

В запросе отправляется объект с параметрами фильтрации, по которым будут отобраны записи с данными RFID-ключей, соответствующие критериям. Далее на сервере подсчитывается количество таких записей и передаётся обратно в качестве ответа. В случае ошибок при проверке параметров фильтра в ответе будет выслан код ошибки.

• Запрос --- GetRecordCountRequest

• Ответ --- GetRecordCountResponse

Параметры запроса:

Примеры запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

using System.Text.Json;
using Google.Protobuf.WellKnownTypes;
using Grpc.Core;
using Grpc.Net.Client;
using IdentityModel.Client;
using Keyapis.Rfidregistry.V1;

// Record uid
var uid = "1234567ABCDEF0";

// GetRecordCount

var getRecordCountResponse = await client.GetRecordCountAsync(new GetRecordCountRequest
{
    Filter = new RecordFilter
    {
        Uids = { uid }
    }
});

Console.WriteLine($"GetRecordCount response: {getRecordCountResponse}\n");

{
  "data": 1
}

1
2

ACCESS_TOKEN="ваш_токен"
grpcurl -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService.GetRecordCount

1
2

ACCESS_TOKEN="ваш_токен"
grpcurl -d '{ \"filter\": { \"rfid_types\": \"CARD\" }}' -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService/GetRecordCount

{
  "data": 21
}

В ответе на запрос количества RFID-ключей сервер возвращает количество доступных ключей с учётом параметров фильтрации или код ошибки в случае некорректного запроса.

Пример ответа:

1
2
3

{
  "data": 3842
}

Метод DeleteRecord позволяет удалять доступные вам RFID-ключи из реестра.

Вы можете удалять только свои RFID-ключи, которые ранее сохранили в реестре ключей под своей учётной записью с токеном доступа. При этом из реестра можно удалить только те записи RFID-ключей, которые ещё не привязаны к активированным ключам, используемым их владельцами.

Обратите внимание, что после удаления RFID-ключа сама запись в реестре остаётся со статусом "Удалён" (Deleted). И теперь добавить RFID-ключ можно только с новым id-идентификатором.

• Запрос --- DeleteRecordRequest

• Ответ --- DeleteRecordResponse

Параметры запроса:

Примеры запроса

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

using System.Text.Json;
using Google.Protobuf.WellKnownTypes;
using Grpc.Core;
using Grpc.Net.Client;
using IdentityModel.Client;
using Keyapis.Rfidregistry.V1;

// Record id
var id = "12345678-9ABC-DEF0-0000-000000000000";

// DeleteRecord

var deleteRecordResponse = await client.DeleteRecordAsync(new DeleteRecordRequest
{
    Id = id
});

Console.WriteLine($"DeleteRecord response: {deleteRecordResponse}\n");

1
2
3
4
5
6
7

ACCESS_TOKEN="ваш_токен"
RECORD_ID="12345678-9ABC-DEF0-0000-000000000000"
grpcurl -d @ -H "Authorization: Bearer $ACCESS_TOKEN" rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.RecordService.DeleteRecord <<EOM
{
"id": "${RECORD_ID}"
}
EOM

В ответе сервера на запрос удаления RFID-ключа из реестра ключей возвращается пустая строка. Это означает успешное удаление ключа, при котором соответствующей записи в реестре присваивается статус "Deleted". В случае ошибки ответ возвращается с кодом этой ошибки.

Метод GetSystemStatus позволяет получить сведения о работоспособности сервиса реестра ключей.

• Запрос --- GetSystemStatusRequest

• Ответ --- GetSystemStatusResponse

В запросе в качестве параметра отправляется пустой объект {} или пустая строка. В случае доступности сервиса возвращается ответ с пустым объектом {} или с кодом ошибки.

Примеры запроса

1
2
3
4
5

// GetSystemStatus

var GetSystemStatusResponse = await client.GetSystemStatusAsync(new GetSystemStatusRequest());

Console.WriteLine($"GetSystemStatus response: {GetSystemStatusResponse}\n");

1

grpcurl rfid-registry-staging.k8s.key.rt.ru:443 keyapis.rfidregistry.v1.SystemService.GetSystemStatus

В ответе сервера на запрос о доступности реестра ключей возвращается пустой объект {}. Это значит, что сервис доступен и функционирует. В случае ошибки ответ возвращается с кодом этой ошибки.