본문 바로가기
WIKI 기술 지식 베이스

API

원문 보기 위키 갱신

소프트웨어 카탈로그 백엔드는 외부 시스템이 활용할 수 있는 JSON 기반 REST API를 제공합니다.

출처: 문서

본문

소프트웨어 카탈로그 백엔드는 외부 시스템이 활용할 수 있는 JSON 기반 REST API를 제공합니다. 이 페이지는 그 형태와 기능을 설명합니다. 이 API의 OpenAPI 스펙은 여기에서 찾을 수 있습니다. OpenAPI 엔드포인트를 시각화하고 브라우저에서 직접 시험해 볼 수 있는 UI는 여기에서 찾을 수 있습니다.

개요

API 표면은 몇 가지 구별되는 기능 그룹으로 구성됩니다. 각각 아래에 전용 섹션이 있습니다.

참고: 이 페이지는 API에서 가장 흔히 쓰이는 일부 부분만 설명하며, 작성 중입니다.

이 문서의 모든 URL 경로는 여러분의 카탈로그 설치를 가리키는 어떤 기본 URL 위에 있다고 가정합니다. 예를 들어 아래 섹션에서 주어진 경로가 /entities이고, 로컬 개발 중 카탈로그가 http://localhost:7007/api/catalog에 있다면 전체 URL은 http://localhost:7007/api/catalog/entities가 됩니다. 실제 URL은 조직마다 다를 수 있으며, 특히 프로덕션에서 그렇지만, 보통 app config의 backend.baseUrl에 끝에 /api/catalog를 붙인 것입니다.

일부 또는 모든 엔드포인트는 Bearer 토큰을 가진 Authorization 헤더를 허용하거나 요구할 수 있으며, 그 토큰은 identity API가 반환한 Backstage 토큰이어야 합니다.

Entities

이들은 엔티티를 직접 읽는 것과 관련된 엔드포인트입니다. 노출하는 것은 최종 엔티티입니다 — 즉 모든 처리와 스티칭 과정의 출력이지, 원래 수집된 원시 엔티티 데이터가 아닙니다. 이 과정과 구분에 대한 자세한 내용은 The Life of an Entity를 참조하세요.

관계 응답 형식

카탈로그 API 응답은 관계 대상을 targetRef 필드로 표현합니다. 더 이상 사용되지 않는 target 객체와 catalog.enableRelationsCompatibility 설정은 제거되었습니다. 외부 카탈로그 API 소비자가 relation.target을 읽는다면, relation.targetRef를 사용하도록 갱신하세요. targetRef 값은 완전한 엔티티 참조입니다.

GET /entities/by-query

엔티티를 쿼리합니다. 아래 섹션에서 설명하는 다음 쿼리 매개변수를 지원합니다.

  • filter — 모든 엔티티의 일부 하위 집합만 선택.
  • fields — 각 엔티티의 전체 데이터 구조 중 일부만 선택.
  • limit — 반환되는 엔티티 수를 제한(기본값은 20).
  • orderField — 엔티티의 순서를 결정.
  • fullTextFilter — 텍스트로 엔티티를 필터링.
  • cursor — 다음 또는 이전 배치의 엔티티를 검색.

반환 타입은 JSON이며 다음 형태입니다.

{  "items": [{ "kind": "Component", "metadata": { "name": "foo" } }],  "totalItems": 4,  "pageInfo": {    "nextCursor": "a-cursor",    "prevCursor": "another-cursor"  }}

필터링

각 엔티티에 대해 일치 여부를 검사하는 필터 집합을 하나 이상 전달할 수 있습니다. 각 필터 집합은 조건이 참이 되려면 모두 일치해야 하는 여러 조건입니다(조건 사이에는 사실상 AND가 있습니다). 엔티티가 결과 집합에 포함되려면 필터 집합 중 하나 이상이 참이어야 합니다(필터 집합 사이에는 사실상 OR가 있습니다).

예:

/entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type  Return entities that match    Filter set 1:      Condition 1: kind = user                   AND      Condition 2: metadata.namespace = default    OR    Filter set 2:      Condition 1: kind = group                   AND      Condition 2: spec.type exists

각 조건은 <key> 또는 <key>=<value> 형태입니다. 첫 번째 형태는 특정 키의 존재(어떤 값이든)를 주장하고, 두 번째 형태는 키가 존재하고 특정 값을 가짐을 주장합니다. 모든 검사는 항상 대소문자를 구분하지 않습니다.

모든 경우에 키는 주어진 엔티티 데이터에서 단순화된 JSON 경로입니다. 경로의 각 부분은 객체의 키이며, 순회는 배열도 내려갑니다. 두 가지 특수 형태가 있습니다.

  • 단순 값 타입(문자열 같은)의 배열 항목은 키가 항목을 문자열로 한 것, 값이 문자열 true인 키-값 쌍으로 일치합니다.
  • 관계는 relations.<type>=<targetRef> 형태로 일치시킬 수 있습니다.

개념을 설명하기 위해 단순화된 예를 살펴보겠습니다.

{  "a": {    "b": ["c", { "d": 1 }],    "e": 7  }}

이것은 다음 조건 중 어느 것과도 일치합니다.

  • a
  • a.b
  • a.b.c
  • a.b.c=true
  • a.b.d
  • a.b.d=1
  • a.e
  • a.e=7

좀 더 실제로 쓸 수 있는 예시들입니다.

  • 모든 고아 엔티티 반환:

/entities/by-query?filter=metadata.annotations.backstage.io/orphan=true

  • 모든 사용자와 그룹 반환:

/entities/by-query?filter=kind=user&filter=kind=group

  • 모든 서비스 컴포넌트 반환:

/entities/by-query?filter=kind=component,spec.type=service

  • java 태그가 있는 모든 엔티티 반환:

/entities/by-query?filter=metadata.tags.java

  • ops 그룹의 멤버인 모든 사용자 반환(그룹의 전체 참조가 사용됨에 주목):

/entities/by-query?filter=kind=user,relations.memberof=group:default/ops

전체 텍스트 필터링

fullTextFilterTerm 쿼리 매개변수를 사용해 엔티티 필드 전체에서 텍스트 검색을 수행할 수 있습니다. 이는 엔티티 YAML 필드의 값에 대해 대소문자를 구분하지 않는 부분 문자열 일치를 수행합니다.

기본적으로 fullTextFilterFields 매개변수를 지정하지 않으면, 현재 정렬 필드(orderField에서) 또는 정렬 필드가 설정되지 않았을 때 metadata.uid에 대해 검색이 실행됩니다. 즉 필드를 명시하지 않으면, 검색이 기대하는 필드와 일치하지 않을 수 있습니다.

어떤 필드를 검색할지 제어하려면 fullTextFilterFields 쿼리 매개변수를 엔티티 필드 경로의 쉼표 구분 목록으로 전달하세요.

쿼리 매개변수:

  • fullTextFilterTerm — 검색할 텍스트(대소문자 구분 없음, 부분 문자열 일치).
  • fullTextFilterFields — 검색 대상 엔티티 필드 경로의 쉼표 구분 목록(예: metadata.name,metadata.title).

예:

/entities/by-query?fullTextFilterTerm=my-service&fullTextFilterFields=metadata.name,metadata.title  Return entities whose metadata.name OR metadata.title contains "my-service"

좀 더 실제로 쓸 수 있는 예시들입니다.

  • 이름으로 컴포넌트 검색:

/entities/by-query?filter=kind=component&fullTextFilterTerm=payment&fullTextFilterFields=metadata.name

  • 이름과 제목 모두에서 검색:

/entities/by-query?filter=kind=system&fullTextFilterTerm=platform&fullTextFilterFields=metadata.name,metadata.title

  • 다른 필터와 결합(예: 특정 그룹 소유):

/entities/by-query?filter=kind=component,relations.ownedBy=group:default/my-team&fullTextFilterTerm=api&fullTextFilterFields=metadata.name

참고

전체 텍스트 필터링은 커서 기반 페이지네이션과 상호 배타적입니다. cursor가 제공되면 fullTextFilterTerm과 fullTextFilterFields는 무시됩니다 — 커서가 이미 초기 요청의 원래 필터 매개변수를 인코딩하고 있기 때문입니다.

필드 선택

기본적으로 전체 엔티티가 반환되지만, 엔티티 데이터의 어떤 부분을 유지할지 선택하는 fields 쿼리 매개변수를 전달할 수 있습니다. 이렇게 하면 응답이 더 작아지고 전송이 빨라지며, 카탈로그가 더 효율적인 쿼리를 수행할 수 있습니다.

쿼리 매개변수 값은 위와 같은 단순화된 JSON 경로의 쉼표 구분 목록입니다. 각 경로는 값의 키 또는 출력에서 유지하고 싶은 하위 트리 루트의 키에 해당합니다. 나머지는 제거됩니다. 예를 들어 ?fields=metadata.name,metadata.annotations,spec을 지정하면 각 엔티티의 metadata에서 name과 annotations 필드만 유지하고(최대 두 개 키를 가진 객체가 됩니다), 전체 spec은 변경하지 않고 유지하며, relations 같은 다른 모든 루트는 잘라냅니다.

좀 더 실제로 쓸 수 있는 예시:

  • 각 엔티티의 전체 참조를 형성할 수 있을 만큼만 반환:

/entities/by-query?fields=kind,metadata.namespace,metadata.name

정렬

기본적으로 엔티티는 내부 uid로 정렬되어 반환됩니다. orderField 쿼리 매개변수를 커스터마이즈해 그 정렬에 영향을 줄 수 있습니다.

예를 들어 이름으로 엔티티를 반환하려면:

/entities/by-query?orderField=metadata.name,asc

각 매개변수 뒤에는 오름차순 사전순을 위한 asc나 내림차순(역순) 사전순을 위한 desc가 올 수 있습니다.

페이지네이션

cursor 쿼리 매개변수를 전달해 엔티티 집합을 커서 기반으로 페이지네이션할 수 있습니다. cursor의 값은 pageInfo 속성 아래 응답에 반환됩니다.

"pageInfo": {    "nextCursor": "a-cursor",    "prevCursor": "another-cursor"  }

nextCursor가 존재하면, 다음 엔티티 배치를 검색하는 데 쓸 수 있습니다. 같은 방식으로 prevCursor가 존재하면, 이전 엔티티 배치를 검색하는 데 쓸 수 있습니다.

  • filter — 모든 엔티티의 일부 하위 집합만 선택.
  • fields — 각 엔티티의 전체 데이터 구조 중 일부만 선택.
  • limit — 반환되는 엔티티 수를 제한(기본값은 20).
  • orderField — 엔티티의 순서를 결정.
  • fullTextFilter 참고: [filter, orderField, fullTextFilter]와 cursor는 상호 배타적입니다. 즉 쿼리 매개변수로 cursor를 전달할 때 [filter, orderField, fullTextFilter] 중 어떤 것도 바꿀 수 없습니다. 그 속성 중 하나라도 바꾸면 페이지네이션에 영향을 주기 때문입니다. filter, orderField, fullTextFilter 중 어떤 것이 cursor와 함께 지정되면, 후자만 고려됩니다.

POST /entities/by-query

이것은 GET 변형과 같은 기능을 지원하지만, URL 길이 제한을 지키지 않아도 되도록 POST 본문에 담습니다. 추가로 더 고급스럽고 표현력 있는 쿼리 형식도 지원합니다 — 아래 참조. 응답 형식은 동일합니다.

필터 조건자로 쿼리하기

카탈로그에서 엔티티의 하위 집합을 선택하기 위해 필터 조건자(predicate)를 전달할 수 있습니다. 그것들은 커스텀 매처($exists, $in, $hasPrefix, $contains 등)를 가질 수 있는 필터 집합으로 끝나는 선택적 논리 표현식 트리($all, $any, $not 사용)로 구성됩니다.

이러한 필터 조건자 표현식이 어떻게 생겼는지의 예입니다.

{  "query": {    "$all": [      {        "kind": "Component",        "spec.type": { "$in": ["service", "website"] }      },      {        "$not": {          "metadata.annotations.backstage.io/orphan": "true"        }      }    ]  }}

필터 집합은 키가 객체 안으로의 점으로 구분된 경로이고, 값이 기본 타입(문자열, 숫자, 또는 불리언) 또는 아래와 같은 커스텀 매처인 객체입니다. 그러한 단순한 필터 집합의 예는 다음과 같습니다.

// All of the following must be true for a given entity (there's an// implicit AND between them){  // The kind field is matched against a literal, case insensitively  "kind": "Component",  // The type field inside the spec is matched using a custom matcher, see below  "spec.type": { "$in": ["service", "website"] }}

쿼리의 루트는 논리 표현식 트리가 있든 없든 항상 객체입니다. $ 기호로 시작하는 단일 키를 가진 노드는 특별한 의미를 갖습니다.

  • $not: 논리 부정. 그 값은 단일 표현식이어야 합니다. 예:
// Matches entities that do NOT have kind Component{  "$not": {    "kind": "Component",  }}

$not은 오른쪽 값 매처에서 사용할 수 없다는 점에 주목하세요.

// ❌ WRONG{ "kind": { "$not": "Component" } }// ✅ CORRECT{ "$not": { "kind": "Component" } }
  • $all: 주어진 모든 표현식이 각 엔티티와 일치하도록 요구. 그 값은 표현식의 배열이어야 합니다. 예:
// Matches entities that BOTH have kind Component and type website{  "$all": [    { "kind": "Component" },    { "spec.type": "website" }  ]}

빈 배열은 항상 모든 엔티티와 일치합니다.

  • $any: 주어진 엔티티와 표현식 집합 중 하나 이상이 일치하도록 요구. 그 값은 표현식의 배열이어야 합니다. 예:
// Matches entities that EITHER have kind Component or type website{  "$any": [    { "kind": "Component" },    { "spec.type": "website" }  ]}

빈 배열은 결코 아무것도 일치하지 않습니다.

  • $exists: 필드의 존재를 주장. 그 값은 true(필드가 엔티티에 존재해야 함, 값이 무엇이든) 또는 false(존재하지 않아야 함)입니다. 예:
// Matches entities that DO NOT have that annotation, ignoring what the// value might be{  "metadata.annotations.backstage.io/orphan": {    "$exists": false  },}
  • $in: 필드가 기본 값 집합 중 하나를 가지도록 주장. 그 값은 문자열, 숫자, 및/또는 불리언 값의 배열이어야 합니다. 예:
// Matches entities whose type is EITHER service or website{  "spec.type": {    "$in": ["service", "website"]  }}

일치는 대소문자를 구분하지 않습니다. 빈 배열은 결코 아무것도 일치하지 않습니다.

  • $hasPrefix: 필드가 특정 접두사 텍스트로 시작하는 문자열이도록 주장. 그 값은 문자열입니다. 예:
// Matches entities whose project slug annotation starts with "backstage/"{  "metadata.annotations.github.com/project-slug": {    "$hasPrefix": "backstage/"  }}

일치는 대소문자를 구분하지 않으며, 정확히 일치하는 것과 주어진 접두사로 시작하는 문자열을 모두 포착합니다.

  • $contains: 배열이 주어진 표현식과 일치하는 요소를 포함하도록 주장. 이 매처에 대한 지원은 제한적입니다. 한 가지 사용 사례는 관계입니다.
{  // Specifically type and (optionally) targetRef supported, and only  // with equality or "$in" for the targetRef  "relations": {    "$contains": {      "type": "ownedBy",      "targetRef": {        "$in": ["user:default/foo", "group:default/bar"]      }    }  }}

다른 사용 사례는 기본 값으로 일치하는 배열, 예를 들어 태그입니다.

{  // Works for array fields whose items are primitive values  // (typically strings, but numbers and booleans are also supported)  "metadata.tags": {    "$contains": "java"  }}

GET /entities

엔티티를 나열합니다.

참고

이 엔드포인트는 더 효율적인 구현과 커서 기반 페이지네이션을 제공하는 GET /entities/by-query를 위해 더 이상 사용되지 않습니다.

이 엔드포인트는 아래 섹션에서 설명하는 다음 쿼리 매개변수를 지원합니다.

  • filter — 모든 엔티티의 일부 하위 집합만 선택.
  • fields — 각 엔티티의 전체 데이터 구조 중 일부만 선택.
  • offset, limit, after — 페이지네이션용.

반환 타입은 JSON이며, Entity의 배열입니다.

필터링

각 엔티티에 대해 일치 여부를 검사하는 필터 집합을 하나 이상 전달할 수 있습니다. 각 필터 집합은 조건이 참이 되려면 모두 일치해야 하는 여러 조건입니다(조건 사이에는 사실상 AND가 있습니다). 엔티티가 결과 집합에 포함되려면 필터 집합 중 하나 이상이 참이어야 합니다(필터 집합 사이에는 사실상 OR가 있습니다).

예:

/entities?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type  Return entities that match    Filter set 1:      Condition 1: kind = user                   AND      Condition 2: metadata.namespace = default    OR    Filter set 2:      Condition 1: kind = group                   AND      Condition 2: spec.type exists

각 조건은 <key> 또는 <key>=<value> 형태입니다. 첫 번째 형태는 특정 키의 존재(어떤 값이든)를 주장하고, 두 번째 형태는 키가 존재하고 특정 값을 가짐을 주장합니다. 모든 검사는 항상 대소문자를 구분하지 않습니다.

모든 경우에 키는 주어진 엔티티 데이터에서 단순화된 JSON 경로입니다. 경로의 각 부분은 객체의 키이며, 순회는 배열도 내려갑니다. 두 가지 특수 형태가 있습니다.

  • 단순 값 타입(문자열 같은)의 배열 항목은 키가 항목을 문자열로 한 것, 값이 문자열 true인 키-값 쌍으로 일치합니다.
  • 관계는 relations.<type>=<targetRef> 형태로 일치시킬 수 있습니다.

개념을 설명하기 위해 단순화된 예를 살펴보겠습니다.

{  "a": {    "b": ["c", { "d": 1 }],    "e": 7  }}

이것은 다음 조건 중 어느 것과도 일치합니다.

  • a
  • a.b
  • a.b.c
  • a.b.c=true
  • a.b.d
  • a.b.d=1
  • a.e
  • a.e=7

좀 더 실제로 쓸 수 있는 예시들입니다.

  • 모든 고아 엔티티 반환:

/entities?filter=metadata.annotations.backstage.io/orphan=true

  • 모든 사용자와 그룹 반환:

/entities?filter=kind=user&filter=kind=group

  • 모든 서비스 컴포넌트 반환:

/entities?filter=kind=component,spec.type=service

  • java 태그가 있는 모든 엔티티 반환:

/entities?filter=metadata.tags.java

  • ops 그룹의 멤버인 모든 사용자 반환(그룹의 전체 참조가 사용됨에 주목):

/entities?filter=kind=user,relations.memberof=group:default/ops

필드 선택

기본적으로 전체 엔티티가 반환되지만, 엔티티 데이터의 어떤 부분을 유지할지 선택하는 fields 쿼리 매개변수를 전달할 수 있습니다. 이렇게 하면 응답이 더 작아지고 전송이 빨라지며, 카탈로그가 더 효율적인 쿼리를 수행할 수 있습니다.

쿼리 매개변수 값은 위와 같은 단순화된 JSON 경로의 쉼표 구분 목록입니다. 각 경로는 값의 키 또는 출력에서 유지하고 싶은 하위 트리 루트의 키에 해당합니다. 나머지는 제거됩니다. 예를 들어 ?fields=metadata.name,metadata.annotations,spec을 지정하면 각 엔티티의 metadata에서 name과 annotations 필드만 유지하고(최대 두 개 키를 가진 객체가 됩니다), 전체 spec은 변경하지 않고 유지하며, relations 같은 다른 모든 루트는 잘라냅니다.

좀 더 실제로 쓸 수 있는 예시:

  • 각 엔티티의 전체 참조를 형성할 수 있을 만큼만 반환:

/entities?fields=kind,metadata.namespace,metadata.name

정렬

기본적으로 엔티티는 정의되지 않았지만 안정적인 순서로 반환됩니다. order 쿼리 매개변수를 하나 이상 전달해 그 순서에 영향을 줄 수 있습니다.

각 매개변수는 오름차순 사전순을 위한 asc: 또는 내림차순(역순) 사전순을 위한 desc:로 시작하고, 그 뒤에 엔티티 키 안으로 점으로 구분된 경로가 옵니다. 정렬은 대소문자를 구분하지 않습니다. 정렬 지시가 하나 이상 주어지면, 나중 지시는 우선순위가 더 낮습니다(더 높은 우선순위의 지시가 같은 값을 가질 때만 적용됩니다).

예:

/entities?order=asc:kind&order=desc:metadata.name

이것은 먼저 종류를 오름차순으로 정렬한 다음, 각 종류 안에서(주어진 종류가 여러 개 있다면) 이름을 내림차순으로 정렬합니다. 결과 집합의 모든 엔티티에 존재하지 않는 필드가 주어지면, 그 필드가 없는 엔티티는 원하는 순서가 어떻든 항상 그 특정 정렬 단계에서 마지막에 정렬됩니다.

페이지네이션

offset과 limit 쿼리 매개변수를 전달해 엔티티 집합을 고전적인 페이지네이션으로 만들 수 있습니다. 커서 기반 페이지네이션을 수행할 때 이전 페이지 다음의 다음 페이지 결과를 반환하는 after 쿼리 매개변수도 있습니다.

다음 페이지의 데이터가 있는 각 페이지네이션 응답은 다음 페이지 쿼리 경로를 가리키는 Link, rel="next" 헤더를 가집니다.

예: 첫 페이지 가져오기:

GET /entities?limit=2HTTP/1.1 200 OKlink: </entities?limit=2&after=eyJsaW...oyfQ%3D%3D>; rel="next"[{"metadata":{...

Link 헤더의 존재를 감지해 다음 페이지 가져오기:

GET /entities?limit=2&after=eyJsaW...oyfQ%3D%3DHTTP/1.1 200 OKlink: </entities?limit=2&after=eyJsaW...o0fQ%3D%3D>; rel="next"[{"metadata":{...

GET /entities/by-uid/<uid>

metadata.uid 필드 값으로 엔티티를 가져옵니다.

반환 타입은 JSON이며, 단일 Entity, 또는 그 UID를 가진 엔티티가 없으면 404 오류입니다.

DELETE /entities/by-uid/<uid>

metadata.uid 필드 값으로 엔티티를 삭제합니다.

참고: 이 삭제 방식은 고아가 된 엔티티에 적합하지만, 로케이션이 적극적으로 갱신하는 "살아있는" 엔티티를 제거하는 데는 적합하지 않습니다. 아래를 읽어 주세요.

가장 흔한 사용자 흐름은 로케이션을 등록하고(아래 참조), 그다음 카탈로그가 그 로케이션과 그로부터 파생될 수 있는 하위 항목의 트리에 맞춰 스스로 최신 상태를 유지하게 하는 것입니다. 즉 카탈로그는 실제 권위 있는 데이터 소스의 실시간 갱신 보기입니다. 카탈로그에서 엔티티를 "살아있게" 유지하는 무언가가 있다면, 이 섹션에서 설명한 방법으로 삭제한 직후 곧 다시 나타날 것입니다. 엔티티를 제대로 제거하려면, 보통 엔티티가 나타나게 하는 로케이션을 등록 해제하는 것이 좋습니다.

하지만 고아가 된 엔티티가 있다면 — 예를 들어 Location 엔티티에서 그 파일에 대한 참조를 제거했거나, 프로세서가 더 이상 엔티티를 생성하지 않는다면 — 이 삭제 방법이 적합합니다.

반환 타입은 이 UID를 가진 엔티티가 존재했든 아니든 항상 빈 204 응답입니다.

GET /entities/by-name/<kind>/<namespace>/<name>

kind, metadata.namespace, metadata.name 필드 값으로 엔티티를 가져옵니다. 이들은 엔티티의 고유 참조 세 쌍을 형성한다는 점에서 특별합니다.

반환 타입은 JSON이며, 단일 Entity, 또는 그 참조 세 쌍을 가진 엔티티가 없으면 404 오류입니다.

GET /entities/by-name/{kind}/{namespace}/{name}/ancestry

엔티티 참조로 엔티티의 혈통(ancestry)을 가져옵니다.

POST /entities/by-refs

엔티티 참조로 엔티티 배치를 가져옵니다. 예를 들어 GraphQL 리졸버에서 대량의 특정 엔티티를 효율적으로 가져오고 싶은 상황에서 유용합니다.

요청 본문은 JSON이며 다음 형태입니다.

{  "entityRefs": ["component:default/foo", "api:default/bar"],  "fields": ["kind", "metadata.name"]}

각 entityRefs 항목은 가져오고 싶은 엔티티 참조입니다. fields 배열은 선택적이며 위의 GET /entities 필드와 같은 방식으로 작동합니다. 즉 각 엔티티의 특정 조각만 가져오는 데 사용됩니다.

반환 타입은 JSON이며 다음 형태입니다.

{  "items": [{ "kind": "Component", "metadata": { "name": "foo" } }, null]}

items 배열은 입력 entityRefs 배열과 같은 길이와 같은 순서를 가집니다. 각 요소는 대응하는 엔티티 데이터를 포함하거나, 그 참조를 가진 엔티티가 카탈로그에 없으면 null입니다.

POST /refresh

entityRef와 관련된 엔티티를 새로고침합니다.

요청 본문은 JSON이며 다음 형태입니다.

{  "entityRef": "<string>"}

POST /validate-entity

전달된 엔티티에 스키마 오류가 없는지 검증합니다.

요청 본문은 JSON이며 다음 형태입니다.

{  "location": "<string>",  "entity": {}}

Locations

GET /locations

로케이션을 나열합니다.

응답 타입은 JSON이며 다음 형태입니다.

[  {    "data": {      "id": "b9784c38-7118-472f-9e22-5638fc73bab0",      "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",      "type": "url"    }  }]

GET /locations/{id}

로케이션 ID로 로케이션을 가져옵니다.

응답 타입은 JSON이며 다음 형태입니다.

{  "id": "b9784c38-7118-472f-9e22-5638fc73bab0",  "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",  "type": "url"}

GET /locations/by-entity/{kind}/{namespace}/{name}

주어진 엔티티를 가리키는 로케이션을 가져옵니다.

응답 타입은 JSON이며 다음 형태입니다.

{  "id": "b9784c38-7118-472f-9e22-5638fc73bab0",  "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",  "type": "url"}

GET /entity-facets?facet=<string>&facet=<string>&filter=<string>&filter=<string>

주어진 필터와 일치하는 모든 엔티티 패싯을 가져옵니다.

응답 타입은 JSON이며 다음 형태입니다.

{  "facets": [    {      "value": "<string>",      "count": 1    }  ]}

POST /locations

카탈로그가 수집할 로케이션을 추가합니다.

성공하면 응답 코드는 HTTP/1.1 201 Created이고 다음 형태의 JSON입니다.

{  "entities": [],  "location": {    "id": "b9784c38-7118-472f-9e22-5638fc73bab0",    "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",    "type": "url"  }}

로케이션이 이미 존재하면 응답은 HTTP/1.1 409 Conflict이고 다음 형태의 JSON입니다.

{  "error": {    "message": "Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists",    "name": "ConflictError",    "stack": "ConflictError: Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists\n..."  },  "request": {    "method": "POST",    "url": "/locations"  },  "response": {    "statusCode": 409  }}

?dryRun=true 쿼리 매개변수를 지원하며, 이는 검증을 수행하고 데이터베이스에 아무것도 쓰지 않습니다. 검증을 성공적으로 통과하면 응답 JSON의 entities 필드에 로케이션에 존재하는 엔티티가 채워집니다.

POST /analyze-location

주어진 로케이션을 검증합니다.

요청 본문은 JSON이며 다음 형태입니다.

{  "location": {    "type": "<string>",    "target": "<string>"  },  "catalogFileName": "<string>"}

그리고 응답 타입은 JSON이며 다음 형태입니다.

{  "generateEntities": [    {      "fields": [        {          "description": "<string>",          "value": "<string>",          "state": "needsUserInput",          "field": "<string>"        },        {          "description": "<string>",          "value": {},          "state": "analysisSuggestedNoValue",          "field": "<string>"        }      ],      "entity": {}    }  ],  "existingEntityFiles": [    {      "entity": "<Entity>",      "isRegistered": "<boolean>",      "location": {        "target": "<string>",        "type": "<string>"      }    }  ]}

DELETE /locations/{id}

ID로 로케이션을 삭제합니다. 성공하면 응답 코드는 HTTP/1.1 204 No Content입니다.

기타

TODO

더 알아보기 (Learn more)