GitLab 구독 내부 API

GitLab 구독 내부 API는 CustomersDot 애플리케이션에서 사용되며, 다른 소비자가 사용할 수 없습니다. 이 문서는 GitLab 및 CustomersDot 코드베이스에서 작업하는 사람들을 위한 것입니다.

새로운 엔드포인트 추가

API 엔드포인트는 기본적으로 외부에서 접근 가능해야 하며, 적절한 인증과 권한 부여가 필요합니다.

새로운 내부 엔드포인트를 추가하기 전에 API가 더 넓은 GitLab 커뮤니티에 이익이 될지 고려하고 외부에서 접근 가능하게 만들 수 있는지 검토하세요.

GitLab Subscription 포털의 경우, 사용자 컨텍스트 없이 GitLab에 업데이트를 수행해야 할 경우 내부 API를 사용할 수 있습니다. 즉, 사용자 액세스 토큰에 접근할 수 없으며, 대신 일반적으로 CustomersDot 애플리케이션으로서 업데이트를 수행합니다.

인증

CustomersDot JWT

이 엔드포인트는 모두 CustomersDot의 JWT 인증을 사용하여 인증됩니다.

JWT를 사용하여 인증하려면, 클라이언트는:

  1. 자격 증명에서 서명 키의 내용을 읽습니다.
  2. 서명 키를 사용하여 JSON 웹 토큰(JWT)을 생성합니다.
  3. X-CUSTOMERS-DOT-INTERNAL-TOKEN 헤더에 JWT를 전달합니다.

관리자 개인 액세스 토큰 (PAT)

이 인증 방법은 Cells 아키텍처에서 지원되지 않으므로 더 이상 사용되지 않습니다. 이는 향후 마일스톤에서 제거될 예정입니다. 대신 JWT 인증을 사용하세요.

관리자로 인증하려면, apiadmin_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_enterpriseproduct_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 EnterpriseProduct 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
  }
}