Интеграция

gRPC API

Обзор публичных gRPC-сервисов Julia, аутентификация метаданными X-Api-Key и примеры вызовов для .NET и Go.

Помимо REST API, Julia предоставляет gRPC API для сервер-серверного взаимодействия (чтение пользователей и отделов, получение публичного ключа, интроспекция и управление API-ключами).

Сгенерированные gRPC-клиенты и исходные .proto-файлы поставляются в официальных пакетах: Cyberzone.Julia.Contracts для .NET и julia-go (contracts/*) для Go. Для других языков (TypeScript, Python и др.) .proto-контракты можно извлечь из каталога protos/ NuGet-пакета или proto/ репозитория julia-go.

Аутентификация gRPC-вызовов

Большинство gRPC-методов требуют аутентификации (исключение — Keys.GetPublicKey). Передавайте сервисный API-ключ в метаданных X-Api-Key (или пользовательский JWT в Authorization: Bearer <token> там, где поддерживаются пользовательские вызовы):

using Cyberzone.Julia.Contracts.User;

builder.Services.AddGrpcClient<Users.UsersClient>(o => o.Address = juliaGrpcUri)
    .AddCallCredentials((_, metadata) =>
    {
        metadata.Add("X-Api-Key", serviceApiKey);
        return Task.CompletedTask;
    });
По умолчанию оба клиента используют TLS (Grpc.Net.Client отправляет CallCredentials только по TLS, а juliagrpc.Dial открывает TLS-соединение). Для внутреннего незашифрованного канала внутри кластера укажите UnsafeUseInsecureChannelCallCredentials = true в ConfigureChannel (.NET) или grpc.WithTransportCredentials(insecure.NewCredentials()) в juliagrpc.Dial (Go).

Доступные gRPC-сервисы

auth.Keys (auth.proto)

Получение текущего публичного ключа подписи JWT.

МетодАвторизацияОписание
GetPublicKeyАнонимныйПринимает PublicKeyType (BASE64 или PEM), возвращает строку public_key

user.Users (user.proto)

Чтение профиля пользователя по UUID.

МетодТребуемые праваОписание
GetUserСервисный Api-Token + authservice.users:readВозвращает id, email, first_name, last_name, middle_name, permissions, groups и departments

Список departments в ответе GetUser фильтруется по правилам видимости: для получения публичных участий сервису достаточно authservice.departments:read:public, для всех участий — authservice.departments.members:read.

department.Departments (department.proto)

Чтение структуры отделов и участников (read-only).

МетодТребуемое правоОписание
GetDepartmentauthservice.departments:readПолная информация об отделе по department_id
GetDepartmentsauthservice.departments:readПлоский список всех отделов
GetDepartmentTreeauthservice.departments:readИерархическое дерево отделов (DepartmentTreeNode)
GetUserDepartmentsauthservice.departments.members:readВсе отделы и роли указанного user_id
GetDepartmentMembersauthservice.departments.members:readВсе участники и их роли в указанном department_id

admin.ApiTokens (admin.proto)

Управление API-ключами и проверка предъявленных ключей.

МетодТребуемое правоОписание
IntrospectApiKeyauthservice.apitokens:introspect (только machine)Проверка ключа и remote_ip, возврат эффективных прав, cache_ttl_seconds и ip_unrestricted
GetApiTokensauthservice.apitokens:read:self (или :read)Список ключей с курсорной пагинацией (page_size, page_token, include_inactive)
GetApiTokenauthservice.apitokens:read:self (или :read)Метаданные конкретного ключа по id
CreateApiTokenauthservice.apitokens:write:self (+ :write для svc)Выпуск нового ключа (полный секрет возвращается в поле token один раз)
RevokeApiTokenauthservice.apitokens:write:self (+ :write для чужих)Идемпотентный отзыв ключа

admin.Permissions (admin.proto)

МетодТребуемое правоОписание
GetPermissionsauthservice.permissions:readЭффективный список прав пользователя по uuid
AddPermissionauthservice.permissions:writeДобавление права пользователю или группе
DeletePermissionauthservice.permissions:writeУдаление права у пользователя или группы

Примеры вызовов

Получение пользователя

using Cyberzone.Julia.Contracts.User;

var user = await usersClient.GetUserAsync(new UserRequest
{
    Id = userId.ToString(),
});

Интроспекция API-ключа

using Cyberzone.Julia.Contracts.Admin;

var result = await apiTokensClient.IntrospectApiKeyAsync(new IntrospectApiKeyRequest
{
    Key = presentedKey,
    RemoteIp = httpContext.Connection.RemoteIpAddress?.ToString() ?? "",
});

if (result.Valid)
{
    // result.Permissions — уже эффективные права; действуйте на их основе
    // Кешируйте по SHA-256(presentedKey) (+ RemoteIp, если !result.IpUnrestricted)
    // на срок не дольше result.CacheTtlSeconds и не позже result.ExpiresAt
}