gRPC API
Помимо 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;
});
import (
"os"
"git.cyberzone.dev/cyberzone/julia-go/contracts/userpb"
"git.cyberzone.dev/cyberzone/julia-go/juliagrpc"
)
conn, err := juliagrpc.Dial("julia.example:443", os.Getenv("JULIA_API_KEY"))
if err != nil {
return err
}
defer conn.Close()
usersClient := userpb.NewUsersClient(conn)
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).
| Метод | Требуемое право | Описание |
|---|---|---|
GetDepartment | authservice.departments:read | Полная информация об отделе по department_id |
GetDepartments | authservice.departments:read | Плоский список всех отделов |
GetDepartmentTree | authservice.departments:read | Иерархическое дерево отделов (DepartmentTreeNode) |
GetUserDepartments | authservice.departments.members:read | Все отделы и роли указанного user_id |
GetDepartmentMembers | authservice.departments.members:read | Все участники и их роли в указанном department_id |
admin.ApiTokens (admin.proto)
Управление API-ключами и проверка предъявленных ключей.
| Метод | Требуемое право | Описание |
|---|---|---|
IntrospectApiKey | authservice.apitokens:introspect (только machine) | Проверка ключа и remote_ip, возврат эффективных прав, cache_ttl_seconds и ip_unrestricted |
GetApiTokens | authservice.apitokens:read:self (или :read) | Список ключей с курсорной пагинацией (page_size, page_token, include_inactive) |
GetApiToken | authservice.apitokens:read:self (или :read) | Метаданные конкретного ключа по id |
CreateApiToken | authservice.apitokens:write:self (+ :write для svc) | Выпуск нового ключа (полный секрет возвращается в поле token один раз) |
RevokeApiToken | authservice.apitokens:write:self (+ :write для чужих) | Идемпотентный отзыв ключа |
admin.Permissions (admin.proto)
| Метод | Требуемое право | Описание |
|---|---|---|
GetPermissions | authservice.permissions:read | Эффективный список прав пользователя по uuid |
AddPermission | authservice.permissions:write | Добавление права пользователю или группе |
DeletePermission | authservice.permissions:write | Удаление права у пользователя или группы |
Примеры вызовов
Получение пользователя
using Cyberzone.Julia.Contracts.User;
var user = await usersClient.GetUserAsync(new UserRequest
{
Id = userId.ToString(),
});
import "git.cyberzone.dev/cyberzone/julia-go/contracts/userpb"
user, err := usersClient.GetUser(ctx, &userpb.UserRequest{
Id: userID.String(),
})
Интроспекция 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
}
import "git.cyberzone.dev/cyberzone/julia-go/contracts/adminpb"
// Прямой gRPC-вызов (либо используйте client.IntrospectAPIKey / juliahttp.WithAPIKeyHeader,
// которые берут локальный парсинг, учёт ip_unrestricted и кеширование на себя):
result, err := apiTokensClient.IntrospectApiKey(ctx, &adminpb.IntrospectApiKeyRequest{
Key: presentedKey,
RemoteIp: remoteIP,
})
if err == nil && result.GetValid() {
// result.GetPermissions() — уже эффективные права; действуйте на их основе
// Кешируйте по SHA-256(presentedKey) (+ remoteIP, если !result.GetIpUnrestricted())
// на срок не дольше result.GetCacheTtlSeconds() и не позже result.GetExpiresAt()
}