GitLab 구독 내부 API
GitLab 구독 내부 API는 CustomersDot 애플리케이션에서 사용되며, 다른 소비자가 사용할 수 없습니다. 이 문서는 GitLab 및 CustomersDot 코드베이스에서 작업하는 사람들을 위한 것입니다.
새로운 엔드포인트 추가
API 엔드포인트는 기본적으로 외부에서 접근 가능해야 하며, 적절한 인증과 권한 부여가 필요합니다.
새로운 내부 엔드포인트를 추가하기 전에 API가 더 넓은 GitLab 커뮤니티에 이익이 될지 고려하고 외부에서 접근 가능하게 만들 수 있는지 검토하세요.
GitLab Subscription 포털의 경우, 사용자 컨텍스트 없이 GitLab에 업데이트를 수행해야 할 경우 내부 API를 사용할 수 있습니다. 즉, 사용자 액세스 토큰에 접근할 수 없으며, 대신 일반적으로 CustomersDot 애플리케이션으로서 업데이트를 수행합니다.
인증
CustomersDot JWT
이 엔드포인트는 모두 CustomersDot의 JWT 인증을 사용하여 인증됩니다.
JWT를 사용하여 인증하려면, 클라이언트는:
- 자격 증명에서 서명 키의 내용을 읽습니다.
- 서명 키를 사용하여 JSON 웹 토큰(
JWT
)을 생성합니다. -
X-CUSTOMERS-DOT-INTERNAL-TOKEN
헤더에 JWT를 전달합니다.
관리자 개인 액세스 토큰 (PAT)
이 인증 방법은 Cells 아키텍처에서 지원되지 않으므로 더 이상 사용되지 않습니다. 이는 향후 마일스톤에서 제거될 예정입니다. 대신 JWT 인증을 사용하세요.
관리자로 인증하려면, api
및 admin_mode
범위에 대한 관리자의 개인 액세스 토큰을 생성합니다. 이 토큰은 PRIVATE-TOKEN
헤더에 제공할 수 있습니다.
내부 엔드포인트
네임스페이스
그룹 소유자 가져오기
GET 명령을 사용하여 네임스페이스의 직접 소유자를 가져옵니다. CustomersDot은 이 엔드포인트를 사용하여 청구 이벤트에 대해 알릴 사용자를 찾습니다.
GET /internal/gitlab_subscriptions/namespaces/:id/owners
예제 요청:
curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/owners"
예제 응답:
[
{
"user": {
"id": 1,
"username": "john_smith",
"name": "John Smith"
},
"access_level": 50,
"notification_email": "name@example.com"
}
]
ID로 네임스페이스 가져오기
네임스페이스에 대한 정보를 가져오는 데 사용됩니다.
GET /internal/gitlab_subscriptions/namespaces/:id
매개변수:
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
id |
정수/문자열 | 예 | 네임스페이스의 ID 또는 URL 인코딩된 경로 |
예제 요청:
curl --request GET --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1"
예제 응답:
{
"id": 1,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"max_seats_used": 0,
"seats_in_use": 0,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
}
네임스페이스 업데이트
기존 네임스페이스를 업데이트하려면 PUT 명령을 사용하세요.
PUT /internal/gitlab_subscriptions/namespaces/:id
매개변수:
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
id |
integer/string | 예 | 네임스페이스의 ID 또는 URL 인코딩된 경로 |
shared_runners_minutes_limit |
integer | 아니요 | 계산된 분 수 쿼터 |
extra_shared_runners_minutes_limit |
integer | 아니요 | 추가 계산 분 수 |
additional_purchased_storage_size |
integer | 아니요 | 추가 저장소 크기 |
additional_purchased_storage_ends_on |
date | 아니요 | 추가로 구매한 저장소 종료일 |
gitlab_subscription_attributes |
hash | 아니요 | GitLab Subscription 속성을 포함하는 해시 오브젝트. seats , max_seats_used , plan_code , end_date , auto_renew , trial , trial_ends_on , trial_starts_on , trial_extension_type 를 수용합니다. |
예제 요청:
curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1 --data '{"shared_runners_minutes_limit":1000}'"
예제 응답:
{
"id": 1,
"name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/group1",
"members_count_with_descendants": 2,
"billable_members_count": 2,
"max_seats_used": 0,
"seats_in_use": 0,
"plan": "default",
"end_date": null,
"trial_ends_on": null,
"trial": false,
"root_repository_size": 100,
"projects_count": 3
}
구독
구독 엔드포인트는
CustomersDot (customers.gitlab.com
)에서 사용되며,
개인 네임스페이스나 GitLab.com의 최상위 그룹에 구독(시험 버전 및 추가 구매 포함)을 적용하는 데 사용됩니다.
구독 정보 가져오기
기존 구독을 보려면 GET 명령을 사용하세요.
GET /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription
예제 요청:
curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/gitlab_subscription"
예제 응답:
{
"plan": {
"code": "premium",
"name": "premium",
"trial": false,
"auto_renew": null,
"upgradable": false,
"exclude_guests": false
},
"usage": {
"seats_in_subscription": 80,
"seats_in_use": 82,
"max_seats_used": 82,
"seats_owed": 2
},
"billing": {
"subscription_start_date": "2020-07-15",
"subscription_end_date": "2021-07-15",
"trial_ends_on": null
}
}
예정된 조정
upcoming_reconciliations
엔드포인트는 CustomersDot (customers.gitlab.com
)에서 네임스페이스의 예정된 조정을 업데이트하는 데 사용됩니다.
예정된 조정 업데이트
PUT /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
namespace_id |
ID | 예 | 예정된 조정이 있는 네임스페이스의 ID |
next_reconciliation_date |
날짜 | 예 | 조정이 발생할 날짜 |
display_alert_from |
날짜 | 예 | 예정된 조정 알림을 표시하기 시작할 날짜 |
예시 요청:
curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" --header "Content-Type: application/json" \
--data '{"upcoming_reconciliations": [{"next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/129/upcoming_reconciliations"
예시 응답:
200
예정된 조정 삭제
예정된 조정을 삭제하려면 DELETE 명령을 사용합니다.
DELETE /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations
예시 요청:
curl --request DELETE \
--url "http://localhost:3000/api/v4/internal/gitlab_subscriptions/namespaces/22/upcoming_reconciliations" \
--header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"
예시 응답:
204
사용자
사용자 검색
GET 명령을 사용하여 사용자 ID를 기반으로 사용자 객체를 가져옵니다.
GET /internal/gitlab_subscriptions/users/:id
예시 요청:
curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/users/:id"
예시 응답:
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"web_url": "http://localhost:3000/john_smith"
}
네임스페이스에서 사용자 권한 가져오기
GET 명령을 사용하여 네임스페이스에서 사용자가 가진 권한을 가져옵니다.
GET /internal/gitlab_subscriptions/namespaces/:namespace_id/user_permissions/:user_id
예시 요청:
curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/:namespace_id/user_permissions/:user_id"
예시 응답:
{
"edit_billing": true
}
신용 카드 유효성 검사 업데이트
PUT 명령을 사용하여 사용자의 신용 카드 유효성 검사를 업데이트합니다.
PUT /internal/gitlab_subscriptions/users/:user_id/credit_card_validation
예시 요청:
curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--data '{"credit_card_validated_at": "2020-01-01 00:00:00 UTC", "credit_card_expiration_year": "2010", "credit_card_expiration_month": "12", "credit_card_holder_name": "John Smith", "credit_card_type": "American Express", "credit_card_mask_number": "1111", "zuora_payment_method_xid": "abc123", "stripe_setup_intent_xid": "seti_abc123", "stripe_payment_method_xid": "pm_abc123", "stripe_card_fingerprint": "card123"}' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/users/:user_id/credit_card_validation"
예시 응답:
{
"success": {}
}
엔드포인트 마이그레이션
이 엔드포인트는 내부 엔드포인트로 마이그레이션될 예정입니다. 이후, 이들은 사용 중단되어 향후 마일스톤에서 제거될 예정입니다.
추가 구매
이 API는 CustomersDot에 의해 Compute Minutes 및 Storage 팩을 제외한 추가 구매 관리를 위해 사용됩니다.
여러 구독 추가 구매 생성 (내부)
POST 명령을 사용하여 여러 구독 추가 구매를 생성, 업데이트 및 배포 해제합니다. 가능한 추가 유형에는 duo_pro
, duo_enterprise
및 product_analytics
가 있습니다.
POST /namespaces/:id/subscription_add_on_purchase
지원되는 속성:
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
quantity |
정수 | 아니오 | 추가 구매의 단위 수. 음이 아닌 정수여야 합니다. (예: Duo Pro 추가 구매용 좌석 수) |
started_on |
날짜 | 예 | 추가 구매가 가능해진 날짜 |
expires_on |
날짜 | 예 | 추가 구매의 만료 날짜 |
purchase_xid |
문자열 | 아니오 | 추가 구매의 식별자 (예: Code Suggestions 추가의 구독 이름) |
trial |
불리언 | 아니오 | 추가가 시험 제품인지 여부 |
성공적으로 수행되면 201
과 다음 응답 속성이 반환됩니다:
속성 | 유형 | 설명 |
---|---|---|
namespace_id |
정수 | 구매와 관련된 네임스페이스의 고유 식별자 |
namespace_name |
문자열 | 구매와 연결된 네임스페이스의 이름 |
add_on |
정수 | 구매와 관련된 추가의 유형. 가능한 추가 유형은 Code Suggestions 별칭 Duo Pro, Duo Enterprise 및 Product Analytics
|
quantity |
정수 | 구독 추가 구매를 위해 구매한 단위 수 |
started_on |
날짜 | 구독 추가가 활성화된 날짜 |
expires_on |
날짜 | 구독 추가가 만료되는 날짜 |
purchase_xid |
문자열 | 구독 추가 구매의 고유 식별자 |
trial |
불리언 | 추가가 시험의 일부인지 여부를 나타냅니다. |
생성/업데이트를 위한 예제 요청:
curl --request POST \
--header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "quantity": 1, "started_on": "<YYYY-MM-DD>", "expires_on": "<YYYY-MM-DD>", "purchase_xid": "A-S0000001", "trial": false }] } }' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases"
배포 해제를 위한 예제 요청:
curl --request POST \
--header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "started_on": "<YYYY-MM-DD>", "expires_on": "<YYYY-MM-DD>" }] } }' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases"
날짜는 요청 전날, 즉 어제의 날짜를 반영해야 합니다.
예제 응답:
[
{
"namespace_id": 1234,
"namespace_name": "namespace-name",
"add_on": "Code Suggestions",
"quantity": 1,
"started_on": "2024-01-01",
"expires_on": "2024-12-31",
"purchase_xid": "A-S0000001",
"trial": false
}
]
구독 추가 구매 생성
POST 명령어를 사용하여 구독 추가 구매를 생성합니다.
POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
quantity |
integer | 예 | 구독 추가 구매의 단위 수 (예: Code Suggestions 추가의 좌석 수) |
started_on |
date | 예 | 구독 추가 구매가 가능해진 날짜 |
expires_on |
date | 예 | 구독 추가 구매의 만료 날짜 |
purchase_xid |
string | 예 | 구독 추가 구매의 식별자 (예: Code Suggestions 추가의 구독 이름) |
trial |
boolean | 아니오 | 추가가 체험인지 여부 |
예제 요청:
curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&started_on="2024-06-15"&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"
예제 응답:
{
"namespace_id":1234,
"namespace_name":"A Namespace Name",
"add_on":"Code Suggestions",
"quantity":10,
"started_on":"2024-06-15",
"expires_on":"2024-07-15",
"purchase_xid":"A-S12345678",
"trial":true
}
구독 추가 구매 업데이트
PUT 명령어를 사용하여 기존의 구독 추가 구매를 업데이트합니다.
PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
quantity |
integer | 아니오 | 구독 추가 구매의 단위 수 (예: Code Suggestions 추가의 좌석 수) |
started_on |
date | 예 | 구독 추가 구매가 가능해진 날짜 |
expires_on |
date | 예 | 구독 추가 구매의 만료 날짜 |
purchase_xid |
string | 아니오 | 구독 추가 구매의 식별자 (예: Code Suggestions 추가의 구독 이름) |
trial |
boolean | 아니오 | 추가가 체험인지 여부 |
예제 요청:
curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&started_on="2024-06-15"&expires_on="2024-07-15"&purchase_xid="A-S12345678"&trial=true"
예제 응답:
{
"namespace_id":1234,
"namespace_name":"A Namespace Name",
"add_on":"Code Suggestions",
"quantity":15,
"started_on":"2024-06-15",
"expires_on":"2024-07-15",
"purchase_xid":"A-S12345678",
"trial":true
}
구독 추가 기능 구매 가져오기
기존 구독 추가 기능 구매를 보려면 GET 명령을 사용하세요.
GET /namespaces/:id/subscription_add_on_purchase/:add_on_name
예제 요청:
curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"
예제 응답:
{
"namespace_id":1234,
"namespace_name":"A Namespace Name",
"add_on":"Code Suggestions",
"quantity":15,
"started_on":"2024-06-15",
"expires_on":"2024-07-15",
"purchase_xid":"A-S12345678",
"trial":true
}
할당량 프로비저닝 계산
- GitLab 16.1에서 “CI/CD 분”에서 “compute quota” 및 “compute minutes”로 이름이 변경되었습니다.
할당량 엔드포인트는 CustomersDot (customers.gitlab.com
)에서 개인 네임스페이스 또는 GitLab.com의 최상위 그룹에 대한 추가 패키지의 compute minutes를 적용하는 데 사용됩니다.
추가 패키지 생성
추가 패키지를 생성하려면 POST 명령을 사용하세요.
POST /namespaces/:id/minutes
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
packs |
array | 예 | 구매한 compute packs의 배열 |
packs[expires_at] |
date | 예 | 구매한 패키지의 만료일 |
packs[number_of_minutes] |
integer | 예 | 추가적인 compute minutes 수 |
packs[purchase_xid] |
string | 예 | 구매의 고유 ID |
예제 요청:
curl --request POST \
--url "http://localhost:3000/api/v4/namespaces/123/minutes" \
--header 'Content-Type: application/json' \
--header 'X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>' \
--data '{
"packs": [
{
"number_of_minutes": 10000,
"expires_at": "2022-01-01",
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
}'
예제 응답:
[
{
"namespace_id": 123,
"expires_at": "2022-01-01",
"number_of_minutes": 10000,
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
추가 패키지 이동
한 네임스페이스에서 다른 네임스페이스로 추가 패키지를 이동하려면 PATCH 명령을 사용하세요.
PATCH /namespaces/:id/minutes/move/:target_id
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
id |
string | 예 | 패키지를 전송할 네임스페이스의 ID |
target_id |
string | 예 | 패키지를 전송할 대상 네임스페이스의 ID |
예제 요청:
curl --request PATCH \
--url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
--header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"
예제 응답:
{
"message": "202 Accepted"
}
구독 (마이그레이션 중)
구독 엔드포인트는
CustomersDot (customers.gitlab.com
)에 의해 사용되어
개인 네임스페이스 또는 GitLab.com의 최상위 그룹에 구독(시험 포함)을 적용합니다.
구독 생성
POST 명령을 사용하여 구독을 생성합니다.
POST /namespaces/:id/gitlab_subscription
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
start_date |
날짜 | 예 | 구독 시작 날짜 |
end_date |
날짜 | 아니오 | 구독 종료 날짜 |
plan_code |
문자열 | 아니오 | 구독 티어 코드 |
seats |
정수 | 아니오 | 구독의 좌석 수 |
max_seats_used |
정수 | 아니오 | 지난 한 달 동안의 최대 활성 사용자 수 |
auto_renew |
불리언 | 아니오 | 종료일에 구독이 자동 갱신되는지 여부 |
trial |
불리언 | 아니오 | 구독이 시험인지 여부 |
trial_starts_on |
날짜 | 아니오 | 시험 시작 날짜 |
trial_ends_on |
날짜 | 아니오 | 시험 종료 날짜 |
예시 요청:
curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"
예시 응답:
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":10,
"seats_in_use":1,
"max_seats_used":0,
"seats_owed":0
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":null,
"trial_ends_on":null
}
}
구독 업데이트
PUT 명령을 사용하여 기존 구독을 업데이트합니다.
PUT /namespaces/:id/gitlab_subscription
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
start_date |
날짜 | 아니오 | 구독 시작 날짜 |
end_date |
날짜 | 아니오 | 구독 종료 날짜 |
plan_code |
문자열 | 아니오 | 구독 티어 코드 |
seats |
정수 | 아니오 | 구독의 좌석 수 |
max_seats_used |
정수 | 아니오 | 지난 한 달 동안의 최대 활성 사용자 수 |
auto_renew |
불리언 | 아니오 | 종료일에 구독이 자동 갱신되는지 여부 |
trial |
불리언 | 아니오 | 구독이 시험인지 여부 |
trial_starts_on |
날짜 | 아니오 | 시험 시작 날짜. 시험이 참이면 필수입니다. |
trial_ends_on |
날짜 | 아니오 | 시험 종료 날짜 |
예시 요청:
curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"
예시 응답:
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":0,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}
더 이상 사용되지 않는 엔드포인트
이 엔드포인트는 CustomersDot에서 더 이상 사용되지 않으며, 이러한 엔드포인트의 내부 버전이 이미 생성되었습니다.
앞으로의 이정표에서 삭제될 예정입니다.
구독(더 이상 사용되지 않음)
이 엔드포인트는 Internal Subscriptions API의 엔드포인트로 대체되었습니다.
구독 가져오기(네임스페이스 API)
기존 구독을 보기 위해 GET 명령을 사용하세요.
GET /namespaces/:id/gitlab_subscription
예시 요청:
curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"
예시 응답:
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false,
"exclude_guests":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":82,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}