GRID

A GRID (Global Resource ID)는 Altium 플랫폼의 모든 엔터티(프로젝트, 컴포넌트, BOM, 작업 등)를 식별하기 위한 전역적으로 고유하고 안정적인 식별자입니다.

GRIDs가 존재하는 이유

플랫폼 엔터티는 일반적으로 로컬 식별자(GUID, 숫자 ID)를 가지며, 이러한 식별자는 각자의 컨텍스트 내에서만 고유합니다. 프로젝트 GUID는 전역적으로 고유하지 않으므로, 서로 다른 Workspace에 있는 두 프로젝트가 동일한 GUID를 가질 수 있습니다. 공급 부품 ID는 공급 시스템 외부에서는 의미가 없습니다. 이 때문에 서비스, 이벤트, 통합 전반에서 엔터티를 모호함 없이 참조하는 것이 불가능합니다.

GRIDs는 필요한 컨텍스트를 식별자 자체에 직접 인코딩함으로써 이 문제를 해결합니다. 영역(area), 테넌트, bounded context, 엔터티 유형, 로컬 ID가 모두 GRID의 일부입니다. GRID만 있으면 플랫폼은 추가 컨텍스트 없이도 해당 엔터티를 찾을 수 있습니다.

형식

GRIDs는 grid를 스킴으로 사용하는 URI입니다.

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

GRIDs는 대소문자를 구분하며 두 개의 주요 부분으로 구성됩니다:

• Context path – area:[tenant-id]:context – :를 구분자로 사용하는 고정 구조

• Resource path – resource-type/resource-id – bounded context에 의해 정의되며, /를 구분자로 사용

리소스 경로는 하위 리소스를 지원합니다: resource-type/id/sub-type/sub-id.

구성 요소

영역 이름은 OAuth scope areas와 일치하며, 의도적으로 제품 및 브랜드에 종속되지 않도록 설계되었습니다. 즉, GRID 형식에는 제품명이 포함되지 않습니다. 따라서 제품 리브랜딩이나 회사 변경이 있더라도 GRIDs는 안정적으로 유지됩니다.

전역 리소스(조직, 사용자, 애플리케이션)의 경우 테넌트 구성 요소가 없습니다. 아래 예시의 이중 콜론(::)에 유의하세요.

예시

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 (Workspace 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 (테넌트 없음 – 부품은 Workspace 소유가 아님):

grid:supply::platform:part/43736907

Common Data Model (CDM)은 플랫폼 엔터티 전반에 걸쳐 정의된 GRIDs의 권위 있는 참조입니다. 여기에는 bounded context, 엔터티 유형, 그리고 해당 GRID 구조가 문서화되어 있습니다.

API에서의 GRIDs

GRIDs는 Altium 365 API에서 엔터티의 id: ID! 필드로 노출됩니다. API는 GraphQL의 Global Object Identification 규칙을 따릅니다. 즉, 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 구조를 사용해 쿼리를 올바른 서브그래프로 라우팅하므로, 호출자로부터 추가 컨텍스트가 필요하지 않습니다.

GRIDs는 API 엔터티 전반에 걸쳐 점진적으로 도입되고 있습니다. 일부 엔터티는 현재 불투명한 base64 인코딩 node ID를 반환하는데, 이는 기반 GraphQL 프레임워크의 레거시 형식입니다. GRID 도입이 확대됨에 따라 이러한 형식은 구조화된 GRID로 대체될 예정입니다.