GitLab 구독 내부 API

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

새 엔드포인트 추가

API 엔드포인트는 기본적으로 외부에서 접근할 수 있어야 하며, 적절한 인증 및 권한이 필요합니다. 새로운 내부 엔드포인트를 추가하기 전에 해당 API가 넓은 GitLab 커뮤니티에 이점을 줄 수 있는지를 고려하고 외부에서 접근할 수 있는지 고려하세요.

GitLab 구독 포털의 경우, 사용자의 컨텍스트 없이 GitLab을 업데이트해야 하는 경우 내부 API를 사용할 수 있습니다. 이는 사용자의 액세스 토큰에 액세스할 수 없고 대신 일반적으로 CustomersDot 애플리케이션으로 업데이트를 수행해야 함을 의미합니다.

인증

CustomersDot JWT

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

JWT를 사용하여 인증하려면, 클라이언트는 다음을 수행합니다.

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

Admin personal access token (PAT)

이 인증 방법은 셀즈 아키텍처에서 지원되지 않기 때문에 더 이상 사용되지 않습니다. 향후 마일스톤에서 제거될 예정입니다. 대신 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 integer/string yes URL-encoded path of the namespace의 ID 또는

예시 요청: 

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 yes URL-encoded path of the namespace의 ID

예시 요청: 

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
}

구독

구독 엔드포인트는 개인 네임스페이스 또는 GitLab.com의 최상위 그룹에 구독(시도, 추가 구매 포함)을 적용하기 위해 CustomersDot에서 사용됩니다.

구독 가져오기

기존 구독을 보기 위해 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 date 예 조정이 발생할 날짜
display_alert_from date 예 다가오는 조정 경고를 시작하는 날짜

예시 요청: 

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"next_reconciliation_date": "2021년 6월 12일", "display_alert_from": "2021년 6월 5일"}]}' \
     "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

사용자

사용자 조회

사용자 ID를 기반으로 사용자 개체를 가져오려면 GET 명령을 사용합니다. 

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": {}
}

구독 애드온 구매 생성

구독 애드온 구매를 만들기 위해 POST 명령어를 사용합니다. 

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name
속성 유형 필수 설명
quantity integer yes 구독 애드온 구매의 단위 수 (예: Code Suggestions 애드온의 좌석 수)
started_on date yes 구독 애드온 구매가 가능해진 날짜
expires_on date yes 구독 애드온 구매의 만료 날짜
purchase_xid string yes 구독 애드온 구매의 식별자 (예: Code Suggestions 애드온의 구독 이름)
trial boolean no 애드온이 시범판인지에 대한 여부

예시 요청: 

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 no 구독 애드온 구매의 단위 수 (예: Code Suggestions 애드온의 좌석 수)
started_on date yes 구독 애드온 구매가 가능해진 날짜
expires_on date yes 구독 애드온 구매의 만료 날짜
purchase_xid string no 구독 애드온 구매의 식별자 (예: Code Suggestions 애드온의 구독 이름)
trial boolean no 애드온이 시범판인지에 대한 여부

예시 요청: 

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 minutes”가 “compute quota” 및 “compute minutes”로 이름이 변경되었습니다.

할당량 프로비저닝 엔드포인트는 CustomersDot (customers.gitlab.com)에서 GitLab.com의 개인 네임스페이스나 최상위 그룹에 추가적인 컴퓨팅 분을 적용하는 데 사용됩니다.

추가 팩 생성

추가 팩을 만들기 위해 POST 명령어를 사용합니다. 

POST /namespaces/:id/minutes
속성 유형 필수 설명
packs array yes 구매한 컴퓨팅 팩의 배열
packs[expires_at] date yes 구매한 팩의 만료 날짜
packs[number_of_minutes] integer yes 추가 컴퓨팅 분의 수
packs[purchase_xid] string yes 구매의 고유 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 date 예 구독 시작일
end_date date 아니요 구독 종료일
plan_code string 아니요 구독 티어 코드
seats integer 아니요 구독 좌석 수
max_seats_used integer 아니요 지난 한 달 동안의 활성 사용자 수
auto_renew boolean 아니요 구독 만료일에 자동 갱신 여부
trial boolean 아니요 구독 시험이면 true
trial_starts_on date 아니요 시험 시작일
trial_ends_on date 아니요 시험 종료일

예시 요청: 

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 date 아니요 구독 시작일
end_date date 아니요 구독 종료일
plan_code string 아니요 구독 티어 코드
seats integer 아니요 구독 좌석 수
max_seats_used integer 아니요 지난 한 달 동안의 활성 사용자 수
auto_renew boolean 아니요 구독 만료일에 자동 갱신 여부
trial boolean 아니요 구독 시험이면 true
trial_starts_on date 아니요 시험 시작일. 시험이 true인 경우 필수
trial_ends_on date 아니요 시험 종료일

예시 요청: 

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에서 사용되지 않으며 내부 버전의 이러한 엔드포인트가 이미 생성되어 있습니다. 이러한 엔드포인트는 향후 마일스톤에서 제거될 예정입니다.

구독 (사용되지 않음)

이러한 엔드포인트는 내부 구독 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
  }
}