СЕТКА
Краткий обзор
- Узнайте, как GRID устраняют неоднозначность при обращении к сущностям в разных рабочих пространствах, сервисах и интеграциях.
- Изучите структуру GRID на примерах глобальных ресурсов, ресурсов рабочего пространства и ресурсов снабжения.
- Узнайте, как API использует GRID для поиска сущностей и маршрутизации запросов, а также как проходит текущий переход с устаревших идентификаторов узлов.
GRID (Global Resource ID) — это глобально уникальный и стабильный идентификатор любой сущности на платформе Altium: проекта, компонента, BOM, задачи и т. д.
Зачем нужны GRID
Сущности платформы обычно имеют локальные идентификаторы (GUID, числовые ID), уникальные только в пределах собственного контекста. GUID проекта не является глобально уникальным: два проекта в разных рабочих пространствах могут иметь одинаковый GUID. Идентификатор поставляемой детали не имеет смысла за пределами системы поставок. Поэтому однозначно ссылаться на сущность в разных сервисах, событиях и интеграциях невозможно.
GRID решают эту проблему, кодируя необходимый контекст непосредственно в идентификаторе: область, арендатор, ограниченный контекст, тип сущности и локальный ID входят в состав GRID. Имея только GRID, платформа может найти сущность без какого-либо дополнительного контекста.
Формат
GRID — это URI, использующие grid в качестве схемы.
grid:area:[tenant-id]:context:resource-type/resource-id
GRID чувствительны к регистру и состоят из двух основных частей:
-
Context path –
area:[tenant-id]:context– фиксированная структура с:в качестве разделителя -
Resource path –
resource-type/resource-id– определяется ограниченным контекстом, с/в качестве разделителя
Путь к ресурсу поддерживает вложенные ресурсы: resource-type/id/sub-type/sub-id.
Составные части
Составная часть |
Обязательна |
Описание |
|
Да |
Общая предметная область платформы — |
|
Нет |
ID арендатора (GUID рабочего пространства для ресурсов рабочего пространства). Отсутствует у ресурсов, не принадлежащих конкретному арендатору |
|
Да |
Ограниченный контекст — |
|
Да |
Понятное человеку имя сущности из терминологии предметной области |
|
Да |
Локальный идентификатор сущности |
Имена областей согласованы с областями действия OAuth и намеренно не привязаны к продуктам и брендам: названия продуктов в формате GRID не используются. Благодаря этому GRID остаются стабильными при ребрендинге продуктов и изменениях в компании.
Для глобальных ресурсов (организаций, пользователей, приложений) составляющая арендатора отсутствует. Обратите внимание на двойное двоеточие (::) в примерах ниже.
Примеры
Global resources (без арендатора):
grid:global::platform:organization/837af973-180e-45ab-a93a-62a66f44d75a
grid:global::platform:user/837af973-180e-45ab-a93a-62a66f44d75a
grid:global::events:subscription/41428e10-d66a-4b27-8bbf-3a51496cceae
Workspace resources (GUID рабочего пространства в качестве арендатора):
grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:design:project/DA051CB4-13C4-41A7-A795-2A5EBC2B9A9B
grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:library:component/0F629FA7-A5C5-4034-829A-83CC5E95B947
grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:procurement:bom/BD74926A-7AFA-454E-8879-C79E8C8685EE
grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:collaboration:task/BCC891F1-49C3-46B2-9A03-85F882133050
Supply resources (без арендатора — детали не принадлежат рабочему пространству):
grid:supply::platform:part/43736907
Common Data Model (CDM) — основной справочник по GRID, определённым для сущностей платформы. В нём описаны ограниченные контексты, типы сущностей и структура их GRID.
GRID в API
В API Altium 365 GRID представлены в виде полей id: ID! сущностей. API следует соглашению GraphQL о глобальной идентификации объектов: имея GRID, платформа может повторно получить сущность напрямую с помощью запроса node:
query {
node(id: "grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:design:adproject/a7ceb47c-db37-426a-a9ef-117d1146be35") {
... on DesProject {
name
description
}
}
}
Шлюз API использует структуру GRID для маршрутизации запроса в нужный подграф. Дополнительный контекст от вызывающей стороны не требуется.
GRID внедряются для сущностей API постепенно. Некоторые сущности пока возвращают непрозрачные идентификаторы узлов в кодировке base64 — это устаревший формат, унаследованный от базового фреймворка GraphQL. По мере расширения использования GRID они будут заменены структурированными GRID.