GRID

Um GRID (Global Resource ID) é um identificador globalmente único e estável para qualquer entidade na plataforma Altium — um projeto, um componente, uma BOM, uma tarefa e assim por diante.

Por que os GRIDs existem

As entidades da plataforma normalmente possuem identificadores locais (GUIDs, IDs numéricos) que são únicos apenas dentro do seu próprio contexto. O GUID de um projeto não é globalmente único — dois projetos em Workspaces diferentes podem compartilhar o mesmo GUID. Um ID de peça de suprimentos não tem significado fora do sistema de suprimentos. Isso torna impossível referenciar uma entidade de forma inequívoca entre serviços, eventos e integrações.

Os GRIDs resolvem isso codificando o contexto necessário diretamente no identificador: a área, o tenant, o contexto delimitado, o tipo de entidade e o ID local fazem parte do GRID. Dado apenas o GRID, a plataforma pode localizar a entidade sem qualquer contexto adicional.

Formato

Os GRIDs são URIs que usam grid como esquema.

grid:area:[tenant-id]:context:resource-type/resource-id

Os GRIDs diferenciam maiúsculas de minúsculas e têm duas partes principais:

• Context path – area:[tenant-id]:context – estrutura fixa usando : como separador

• Resource path – resource-type/resource-id – definido pelo contexto delimitado, usando / como separador

O caminho do recurso oferece suporte a sub-recursos: resource-type/id/sub-type/sub-id.

Componentes

Os nomes de área estão alinhados com as áreas de escopo OAuth e são intencionalmente agnósticos em relação a produto e marca — nenhum nome de produto aparece no formato GRID. Isso torna os GRIDs estáveis diante de mudanças de marca de produtos e da empresa.

Para recursos globais (organizações, usuários, aplicações), o componente tenant está ausente — observe os dois-pontos duplos (::) nos exemplos abaixo.

Exemplos

Global resources (sem tenant):

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 do Workspace como tenant):

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 (sem tenant — as peças não pertencem a Workspaces):

grid:supply::platform:part/43736907

O Common Data Model (CDM) é a referência oficial para GRIDs definidos entre entidades da plataforma. Ele documenta os contextos delimitados, os tipos de entidade e sua estrutura GRID.

GRIDs na API

Os GRIDs aparecem na API do Altium 365 como campos id: ID! nas entidades. A API segue a convenção GraphQL de Global Object Identification — dado um GRID, a plataforma pode buscar novamente a entidade diretamente usando a consulta node:

query {
  node(id: "grid:workspace:d2e3a7b0-4eb4-4339-a3d6-20276ca4f7eb:design:adproject/a7ceb47c-db37-426a-a9ef-117d1146be35") {
    ... on DesProject {
      name
      description
    }
  }
}

O gateway da API usa a estrutura do GRID para encaminhar a consulta ao subgrafo correto — nenhum contexto adicional é necessário por parte de quem faz a chamada.

Os GRIDs estão sendo adotados progressivamente entre as entidades da API. Algumas entidades atualmente retornam IDs de nó opacos codificados em base64 — um formato legado da infraestrutura GraphQL subjacente. À medida que a adoção de GRIDs se expandir, eles serão substituídos por GRIDs estruturados.