팀(Team) API

팀(Team) API

이 API는 팀과 팀 구성원(Team Memberships)을 관리하는 데 사용할 수 있어요.

이 API 엔드포인트에 대한 접근은 다음과 같이 제한돼요:

  • 인증된 모든 사용자는 자신이 속한 팀의 세부 정보를 볼 수 있어요.
  • 조직 관리자(Organization Admin)는 모든 팀과 팀 구성원을 관리할 수 있어요.

⚠️ Grafana 13부터 /api 엔드포인트가 /apis 라우트로 대체되어 더 이상 사용되지 않게(deprecated) 되고 있어요. Grafana가 기존 API를 마이그레이션하는 동안 현재 사용 중인 레거시 API와 정확히 일치하지 않을 수 있어요. 이 변경으로 현재 설정이 중단되거나 깨지지는 않아요. 레거시 API는 비활성화되지 않으며 완전히 접근·사용 가능하지만, /api 라우트는 더 이상 업데이트되지 않아요. 자세한 내용은 "Grafana의 새 API 구조" 문서를 참조해요.

Grafana Enterprise를 사용 중이라면 일부 엔드포인트에 특정 권한이 필요해요. 자세한 내용은 "Role-based access control permissions" 문서를 참조해요.

출처: 문서

본문

페이지네이션이 있는 팀 검색

GET /api/teams/search?perpage=50&page=1&query=myteam&sort=memberCount-desc

또는

GET /api/teams/search?name=myteam

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:read teams:*

예제 요청:

GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "MyTestTeam",
      "email": "",
      "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
      "memberCount": 1
    }
  ],
  "page": 1,
  "perPage": 1000
}

query 매개변수 사용

perpage 매개변수의 기본값은 1000, page 매개변수의 기본값은 1이에요.

응답의 totalCount 필드는 팀 목록의 페이지네이션에 사용할 수 있어요. 예를 들어 totalCount가 100팀이고 perpage가 10으로 설정되어 있다면 팀 페이지는 10개예요.

query 매개변수는 선택 사항이며, query 값이 name 필드에 포함된 결과를 반환해요. 공백이 있는 query 값은 URL 인코딩해야 해요. 예: query=my%20team.

sort 매개변수는 검색 결과를 정렬할 선택적 쉼표 구분 목록이에요. sort 필터에 허용되는 값: name-asc, name-desc, email-asc, email-desc, memberCount-asc, memberCount-desc. 기본적으로 sort를 지정하지 않으면 팀 목록은 name 오름차순으로 정렬돼요.

name 매개변수 사용

name 매개변수는 매개변수가 name 필드와 일치하면 단일 팀을 반환해요.

상태 코드:

  • 200 - Ok
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found (이름으로 검색할 때)

Id로 팀 가져오기

GET /api/teams/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:read teams:*

예제 요청:

GET /api/teams/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "orgId": 1,
  "name": "MyTestTeam",
  "email": "",
  "created": "2017-12-15T10:40:45+01:00",
  "updated": "2017-12-15T10:40:45+01:00"
}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found

팀 추가

팀 name은 고유해야 해요. name은 필수이고 email은 선택 사항이에요.

POST /api/teams

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:create N/A

예제 요청:

POST /api/teams HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "name": "MyTestTeam",
  "email": "[email protected]",
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team created","teamId":2,"uid":"ceaulqadfoav4e"}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 409 - Team name is taken

팀 업데이트

팀에 대해 업데이트할 수 있는 두 필드: name과 email.

PUT /api/teams/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:write teams:*

예제 요청:

PUT /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "name": "MyTestTeam",
  "email": "[email protected]"
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team updated"}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found
  • 409 - Team name is taken

Id로 팀 삭제

DELETE /api/teams/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:delete teams:*

예제 요청:

DELETE /api/teams/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team deleted"}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Failed to delete Team. ID not found

팀 구성원 가져오기

GET /api/teams/:teamId/members

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams.permissions:read teams:*

예제 요청:

GET /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 3,
    "email": "[email protected]",
    "login": "user1",
    "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79"
  },
  {
    "orgId": 1,
    "teamId": 1,
    "userId": 2,
    "email": "[email protected]",
    "login": "user2",
    "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e"
  }
]

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied

팀 구성원 추가

POST /api/teams/:teamId/members

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams.permissions:write teams:*

예제 요청:

POST /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "userId": 2
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Member added to Team"}

상태 코드:

  • 200 - Ok
  • 400 - User is already added to this team
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found

팀에서 구성원 제거

DELETE /api/teams/:teamId/members/:userId

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams.permissions:write teams:*

예제 요청:

DELETE /api/teams/2/members/3 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team Member removed"}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found / Team member not found

팀 구성원 일괄 업데이트

사용자 이메일을 사용해 팀 구성원과 관리자를 일괄 업데이트할 수 있어요. 지정된 팀의 현재 모든 구성원과 관리자를 덮어써요.

PUT /api/teams/:teamId/members

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams.permissions:write teams:*

예제 요청:

PUT /api/teams/1/members HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "members": ["[email protected]", "[email protected]"]
  "admins": ["[email protected]"]
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{"message":"Team memberships have been updated"}

상태 코드:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Permission denied
  • 404 - Team not found / Team member not found
  • 500 - Internal error

팀 환경설정 가져오기

GET /api/teams/:teamId/preferences

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:read teams:*

예제 요청:

GET /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "theme": "",
  "homeDashboardId": 0,
  "homeDashboardUID": "",
  "timezone": ""
}

팀 환경설정 업데이트

PUT /api/teams/:teamId/preferences

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
teams:write teams:*

예제 요청:

PUT /api/teams/2/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "theme": "dark",
  "homeDashboardId": 39,
  "homeDashboardUID": "jcIIG-07z",
  "timezone": "utc"
}

JSON body 스키마:

  • theme - light, dark 중 하나, 또는 기본 테마의 경우 빈 문자열.
  • homeDashboardId - 더 이상 사용되지 않음(deprecated). homeDashboardUID를 사용해요.
  • homeDashboardUID - 대시보드의 :uid.
  • timezone - utc, browser 중 하나, 또는 기본값의 경우 빈 문자열.

키를 생략하면 현재 값이 시스템 기본값으로 대체돼요.

예제 응답:

HTTP/1.1 200
Content-Type: text/plain; charset=utf-8

{
  "message":"Preferences updated"
}

더 알아보기 (Learn more)

  • 팀 및 조직 관리 개요
  • Grafana의 새 API 구조