InfoGrab DocsInfoGrab Docs

GitLab 구독 내부 API

요약

GitLab 구독 내부 API는 CustomersDot 애플리케이션에서 사용하며, 다른 소비자는 사용할 수 없습니다. API 엔드포인트는 기본적으로 적절한 인증 및 인가와 함께 외부에서 접근 가능해야 합니다. GitLab 구독 포털의 경우, 사용자 컨텍스트 없이 GitLab을 업데이트해야 할 때 내부 API를 사용할 수 있습니다.

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

새 엔드포인트 추가#

API 엔드포인트는 기본적으로 적절한 인증 및 인가와 함께 외부에서 접근 가능해야 합니다. 새로운 내부 엔드포인트를 추가하기 전에, 해당 API가 더 넓은 GitLab 커뮤니티에 도움이 될 수 있는지, 그리고 외부에서 접근 가능하게 만들 수 있는지 검토하세요.

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

인증#

CustomersDot JWT#

이 엔드포인트들은 모두 CustomersDot의 JWT 인증을 사용합니다.

JWT로 인증하려면 클라이언트가 다음을 수행합니다:

  • 자격 증명에서 서명 키의 내용을 읽습니다.

  • 서명 키를 사용하여 JSON Web Token(JWT)을 생성합니다.

  • X-CUSTOMERS-DOT-INTERNAL-TOKEN 헤더에 JWT를 전달합니다.

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

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

관리자로 인증하려면 apiadmin_mode 스코프를 가진 관리자용 개인 액세스 토큰을 생성하세요. 이 토큰은 PRIVATE-TOKEN 헤더에 제공할 수 있습니다.

내부 엔드포인트#

네임스페이스#

그룹 Owner 가져오기#

GET 명령을 사용하여 네임스페이스의 직접 Owner를 가져옵니다. 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 네임스페이스의 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 yes 네임스페이스의 ID 또는 URL 인코딩된 경로
shared_runners_minutes_limit integer no 컴퓨트 분 할당량
extra_shared_runners_minutes_limit integer no 추가 컴퓨트 분
additional_purchased_storage_size integer no 추가 스토리지 크기
additional_purchased_storage_ends_on date no 추가 구매 스토리지 종료일
gitlab_subscription_attributes hash no GitLab 구독 속성을 포함하는 해시 오브젝트. 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
}

네임스페이스 프로비저닝#

루트 네임스페이스에 대한 구독 관련 리소스를 프로비저닝하는 데 사용합니다. 여기에는 기본 제품, 스토리지, 컴퓨트 분, 애드온 구매가 포함됩니다. 엔드포인트는 리소스를 독립적으로 처리합니다. 하나의 리소스 프로비저닝에 실패하더라도 다른 리소스는 계속 프로비저닝됩니다.

제공된 파라미터에 따라 단일 요청으로 하나 이상의 리소스를 프로비저닝할 수 있습니다.

POST /internal/gitlab_subscriptions/namespaces/:id/provision

파라미터:

속성 타입 필수 여부 설명
id integer yes 프로비저닝할 네임스페이스의 ID

엔드포인트는 provision 루트 키 하위에 중첩된 각 리소스의 파라미터를 지원합니다:

속성 타입 필수 여부 설명
base_product hash no GitLab 구독 속성을 포함하는 해시 오브젝트
storage hash no 스토리지 속성을 포함하는 해시 오브젝트
compute_minutes hash no 컴퓨트 분 속성을 포함하는 해시 오브젝트
add_on_purchases hash no 애드온 구매 속성을 포함하는 해시 오브젝트

기본 제품 지원 속성:

속성 타입 필수 여부 설명
plan_code string no 구독 티어 코드
start_date date no 구독 시작일
end_date date no 구독 종료일
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수
trial_ends_on date no 평가판 종료일

스토리지 지원 속성:

속성 타입 필수 여부 설명
additional_purchased_storage_size integer no 추가 스토리지 크기
additional_purchased_storage_ends_on date no 추가 구매 스토리지 종료일

컴퓨트 분 지원 속성:

속성 타입 필수 여부 설명
shared_runners_minutes_limit integer no 컴퓨트 분 할당량
extra_shared_runners_minutes_limit integer no 추가 컴퓨트 분

애드온 구매 지원 속성:

속성 타입 필수 여부 설명
quantity integer No 구독 애드온 구매의 단위 수. 음수가 아닌 정수여야 합니다. (예: GitLab Duo Pro 애드온의 시트 수)
started_on date Yes 구독 애드온 구매가 사용 가능하게 된 날짜
expires_on date Yes 구독 애드온 구매의 만료일
purchase_xid string No 구독 애드온 구매의 식별자 (예: GitLab Duo Pro 애드온의 구독 이름)
trial boolean No 애드온이 평가판인지 여부

요청 예시:

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1/provision" \
--data '{
  "provision": {
    "base_product": {
      "plan_code": "ultimate",
      "seats": 30,
      "start_date": "2024-01-01",
      "end_date": "2025-01-01",
      "max_seats_used": 10,
      "auto_renew": true,
      "trial": false,
      "trial_starts_on": null,
      "trial_ends_on": null
    },
    "storage": {
      "additional_purchased_storage_size": 100,
      "additional_purchased_storage_ends_on": "2025-01-01"
    },
    "compute_minutes": {
      "extra_shared_runners_minutes_limit": 90,
      "shared_runners_minutes_limit": 100
    },
    "add_on_purchases": {
      "duo_enterprise": [{
        "started_on": "2024-01-01",
        "expires_on": "2025-01-01",
        "purchase_xid": "A-S00001",
        "quantity": 1,
        "trial": false
      }]
    }
  }
}'

응답 상태 코드:

  • 200 OK - 네임스페이스가 성공적으로 프로비저닝됨 (빈 응답)

  • 400 Bad Request - 잘못된 파라미터 또는 루트가 아닌 네임스페이스

  • 401 Unauthorized - 유효하지 않은 토큰

  • 404 Not Found - 네임스페이스가 존재하지 않음

  • 422 Unprocessable Entity - 프로비저닝 중 유효성 검사 오류

구독#

구독 엔드포인트는 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
  }
}

구독 생성#

POST 명령을 사용하여 구독을 생성합니다.

POST /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription
속성 타입 필수 여부 설명
start_date date yes 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일
trial_ends_on date no 평가판 종료일

요청 예시:

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/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 /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription
속성 타입 필수 여부 설명
start_date date no 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수.
trial_ends_on date no 평가판 종료일

요청 예시:

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/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
  }
}

예정된 조정#

upcoming_reconciliations 엔드포인트는 CustomersDot(customers.gitlab.com)에서 네임스페이스의 예정된 조정을 업데이트하는 데 사용됩니다.

예정된 조정 업데이트#

PUT /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations
속성 타입 필수 여부 설명
namespace_id ID yes 예정된 조정이 있는 네임스페이스의 ID
next_reconciliation_date date yes 조정이 발생할 날짜
display_alert_from date yes 예정된 조정 알림을 표시하기 시작할 날짜

요청 예시:

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 명령을 사용하여 upcoming_reconciliation을 삭제합니다.

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를 기반으로 User 오브젝트를 가져옵니다.

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에서 컴퓨트 분 및 스토리지 팩을 제외한 애드온 구매를 관리하는 데 사용됩니다.

여러 구독 애드온 구매 생성 (내부)#

POST 명령을 사용하여 여러 구독 애드온 구매를 생성, 업데이트 및 프로비저닝 해제합니다. 가능한 애드온 유형은 duo_pro, duo_enterprise, product_analytics입니다.

POST /internal/gitlab_subscriptions/namespaces/:id/subscription_add_on_purchases

지원 속성:

속성 타입 필수 여부 설명
quantity integer No 구독 애드온 구매의 단위 수. 음수가 아닌 정수여야 합니다. (예: GitLab Duo Pro 애드온의 시트 수)
started_on date Yes 구독 애드온 구매가 사용 가능하게 된 날짜
expires_on date Yes 구독 애드온 구매의 만료일
purchase_xid string No 구독 애드온 구매의 식별자 (예: Code Suggestions 애드온의 구독 이름)
trial boolean No 애드온이 평가판인지 여부

성공 시 201과 다음 응답 속성을 반환합니다:

속성 타입 설명
namespace_id integer 구매와 연관된 네임스페이스의 고유 식별자
namespace_name string 구매와 연결된 네임스페이스의 이름
add_on integer 구매와 관련된 애드온 유형. 가능한 애드온 유형은 Code Suggestions(GitLab Duo Pro의 별칭), Duo Enterprise, Product Analytics
quantity integer 구독 애드온에 대해 구매한 단위 수
started_on date 구독 애드온이 활성화된 날짜
expires_on date 구독 애드온이 만료될 날짜
purchase_xid string 구독 애드온 구매의 고유 식별자
trial boolean 애드온이 평가판의 일부인지 여부

생성/업데이트 요청 예시:

curl --request POST \
--header --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "quantity": 1, "started_on": "", "expires_on": "", "purchase_xid": "C-00123456", "trial": false }] } }' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases"

프로비저닝 해제 요청 예시:

curl --request POST \
--header --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "started_on": "", "expires_on": "" }] } }' \
"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": "C-00123456",
    "trial": false
  }
]

구독 애드온 구매 가져오기#

GET 명령을 사용하여 기존 구독 애드온 구매를 조회합니다.

GET /internal/gitlab_subscriptions/namespaces/:id/subscription_add_on_purchases/:add_on_name

요청 예시:

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases/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":"C-00123456",
  "trial":true
}

컴퓨트 분 프로비저닝#

컴퓨트 분 엔드포인트는 CustomersDot(customers.gitlab.com)에서 GitLab.com의 개인 네임스페이스 또는 최상위 그룹에 추가 컴퓨트 분 팩을 적용하는 데 사용됩니다.

추가 팩 생성#

POST 명령을 사용하여 추가 팩을 생성합니다.

POST /internal/gitlab_subscriptions/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/internal/gitlab_subscriptions/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": "C-00123456"
      }
    ]
  }'

응답 예시:

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "C-00123456"
  }
]

추가 팩 이동#

PATCH 명령을 사용하여 추가 팩을 한 네임스페이스에서 다른 네임스페이스로 이동합니다.

PATCH /internal/gitlab_subscriptions/namespaces/:id/minutes/move/:target_id
속성 타입 필수 여부 설명
id string yes 팩을 이전할 네임스페이스의 ID
target_id string yes 팩을 받을 타깃 네임스페이스의 ID

요청 예시:

curl --request PATCH \
  --url "http://localhost:3000/api/v4/internal/gitlab_subscriptions/namespaces/123/minutes/move/321" \
  --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"

응답 예시:

{
  "message": "202 Accepted"
}

더 이상 사용되지 않는 엔드포인트#

이 엔드포인트들은 내부 엔드포인트로 마이그레이션되었습니다. 현재 더 이상 사용되지 않으며 향후 마일스톤에서 제거될 예정입니다.

애드온 구매 (더 이상 사용되지 않음)#

이 API는 CustomersDot에서 컴퓨트 분 및 스토리지 팩을 제외한 애드온 구매를 관리하는 데 사용됩니다.

구독 애드온 구매 생성 (더 이상 사용되지 않음)#

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="C-00123456"&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":"C-00123456",
  "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="C-00123456"&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":"C-00123456",
  "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":"C-00123456",
  "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": "C-00123456"
      }
    ]
  }'

응답 예시:

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "C-00123456"
  }
]

추가 팩 이동 (더 이상 사용되지 않음)#

PATCH 명령을 사용하여 추가 팩을 한 네임스페이스에서 다른 네임스페이스로 이동합니다.

PATCH /namespaces/:id/minutes/move/:target_id
속성 타입 필수 여부 설명
id string yes 팩을 이전할 네임스페이스의 ID
target_id string yes 팩을 받을 타깃 네임스페이스의 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 yes 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 지난 한 달 동안의 최대 활성 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일
trial_ends_on date no 평가판 종료일

요청 예시:

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 no 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 지난 한 달 동안의 최대 활성 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수.
trial_ends_on date no 평가판 종료일

요청 예시:

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
  }
}

구독 가져오기 (더 이상 사용되지 않음)#

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
  }
}

GitLab 구독 내부 API

GitLab v19.1
원문 보기
요약

GitLab 구독 내부 API는 CustomersDot 애플리케이션에서 사용하며, 다른 소비자는 사용할 수 없습니다. API 엔드포인트는 기본적으로 적절한 인증 및 인가와 함께 외부에서 접근 가능해야 합니다. GitLab 구독 포털의 경우, 사용자 컨텍스트 없이 GitLab을 업데이트해야 할 때 내부 API를 사용할 수 있습니다.

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

새 엔드포인트 추가#

API 엔드포인트는 기본적으로 적절한 인증 및 인가와 함께 외부에서 접근 가능해야 합니다. 새로운 내부 엔드포인트를 추가하기 전에, 해당 API가 더 넓은 GitLab 커뮤니티에 도움이 될 수 있는지, 그리고 외부에서 접근 가능하게 만들 수 있는지 검토하세요.

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

인증#

CustomersDot JWT#

이 엔드포인트들은 모두 CustomersDot의 JWT 인증을 사용합니다.

JWT로 인증하려면 클라이언트가 다음을 수행합니다:

  • 자격 증명에서 서명 키의 내용을 읽습니다.

  • 서명 키를 사용하여 JSON Web Token(JWT)을 생성합니다.

  • X-CUSTOMERS-DOT-INTERNAL-TOKEN 헤더에 JWT를 전달합니다.

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

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

관리자로 인증하려면 apiadmin_mode 스코프를 가진 관리자용 개인 액세스 토큰을 생성하세요. 이 토큰은 PRIVATE-TOKEN 헤더에 제공할 수 있습니다.

내부 엔드포인트#

네임스페이스#

그룹 Owner 가져오기#

GET 명령을 사용하여 네임스페이스의 직접 Owner를 가져옵니다. 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 네임스페이스의 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 yes 네임스페이스의 ID 또는 URL 인코딩된 경로
shared_runners_minutes_limit integer no 컴퓨트 분 할당량
extra_shared_runners_minutes_limit integer no 추가 컴퓨트 분
additional_purchased_storage_size integer no 추가 스토리지 크기
additional_purchased_storage_ends_on date no 추가 구매 스토리지 종료일
gitlab_subscription_attributes hash no GitLab 구독 속성을 포함하는 해시 오브젝트. 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
}

네임스페이스 프로비저닝#

루트 네임스페이스에 대한 구독 관련 리소스를 프로비저닝하는 데 사용합니다. 여기에는 기본 제품, 스토리지, 컴퓨트 분, 애드온 구매가 포함됩니다. 엔드포인트는 리소스를 독립적으로 처리합니다. 하나의 리소스 프로비저닝에 실패하더라도 다른 리소스는 계속 프로비저닝됩니다.

제공된 파라미터에 따라 단일 요청으로 하나 이상의 리소스를 프로비저닝할 수 있습니다.

POST /internal/gitlab_subscriptions/namespaces/:id/provision

파라미터:

속성 타입 필수 여부 설명
id integer yes 프로비저닝할 네임스페이스의 ID

엔드포인트는 provision 루트 키 하위에 중첩된 각 리소스의 파라미터를 지원합니다:

속성 타입 필수 여부 설명
base_product hash no GitLab 구독 속성을 포함하는 해시 오브젝트
storage hash no 스토리지 속성을 포함하는 해시 오브젝트
compute_minutes hash no 컴퓨트 분 속성을 포함하는 해시 오브젝트
add_on_purchases hash no 애드온 구매 속성을 포함하는 해시 오브젝트

기본 제품 지원 속성:

속성 타입 필수 여부 설명
plan_code string no 구독 티어 코드
start_date date no 구독 시작일
end_date date no 구독 종료일
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수
trial_ends_on date no 평가판 종료일

스토리지 지원 속성:

속성 타입 필수 여부 설명
additional_purchased_storage_size integer no 추가 스토리지 크기
additional_purchased_storage_ends_on date no 추가 구매 스토리지 종료일

컴퓨트 분 지원 속성:

속성 타입 필수 여부 설명
shared_runners_minutes_limit integer no 컴퓨트 분 할당량
extra_shared_runners_minutes_limit integer no 추가 컴퓨트 분

애드온 구매 지원 속성:

속성 타입 필수 여부 설명
quantity integer No 구독 애드온 구매의 단위 수. 음수가 아닌 정수여야 합니다. (예: GitLab Duo Pro 애드온의 시트 수)
started_on date Yes 구독 애드온 구매가 사용 가능하게 된 날짜
expires_on date Yes 구독 애드온 구매의 만료일
purchase_xid string No 구독 애드온 구매의 식별자 (예: GitLab Duo Pro 애드온의 구독 이름)
trial boolean No 애드온이 평가판인지 여부

요청 예시:

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1/provision" \
--data '{
  "provision": {
    "base_product": {
      "plan_code": "ultimate",
      "seats": 30,
      "start_date": "2024-01-01",
      "end_date": "2025-01-01",
      "max_seats_used": 10,
      "auto_renew": true,
      "trial": false,
      "trial_starts_on": null,
      "trial_ends_on": null
    },
    "storage": {
      "additional_purchased_storage_size": 100,
      "additional_purchased_storage_ends_on": "2025-01-01"
    },
    "compute_minutes": {
      "extra_shared_runners_minutes_limit": 90,
      "shared_runners_minutes_limit": 100
    },
    "add_on_purchases": {
      "duo_enterprise": [{
        "started_on": "2024-01-01",
        "expires_on": "2025-01-01",
        "purchase_xid": "A-S00001",
        "quantity": 1,
        "trial": false
      }]
    }
  }
}'

응답 상태 코드:

  • 200 OK - 네임스페이스가 성공적으로 프로비저닝됨 (빈 응답)

  • 400 Bad Request - 잘못된 파라미터 또는 루트가 아닌 네임스페이스

  • 401 Unauthorized - 유효하지 않은 토큰

  • 404 Not Found - 네임스페이스가 존재하지 않음

  • 422 Unprocessable Entity - 프로비저닝 중 유효성 검사 오류

구독#

구독 엔드포인트는 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
  }
}

구독 생성#

POST 명령을 사용하여 구독을 생성합니다.

POST /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription
속성 타입 필수 여부 설명
start_date date yes 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일
trial_ends_on date no 평가판 종료일

요청 예시:

curl --request POST --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/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 /internal/gitlab_subscriptions/namespaces/:id/gitlab_subscription
속성 타입 필수 여부 설명
start_date date no 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 현재 구독 기간 내 청구 가능한 최대 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수.
trial_ends_on date no 평가판 종료일

요청 예시:

curl --request PUT --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/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
  }
}

예정된 조정#

upcoming_reconciliations 엔드포인트는 CustomersDot(customers.gitlab.com)에서 네임스페이스의 예정된 조정을 업데이트하는 데 사용됩니다.

예정된 조정 업데이트#

PUT /internal/gitlab_subscriptions/namespaces/:namespace_id/upcoming_reconciliations
속성 타입 필수 여부 설명
namespace_id ID yes 예정된 조정이 있는 네임스페이스의 ID
next_reconciliation_date date yes 조정이 발생할 날짜
display_alert_from date yes 예정된 조정 알림을 표시하기 시작할 날짜

요청 예시:

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 명령을 사용하여 upcoming_reconciliation을 삭제합니다.

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를 기반으로 User 오브젝트를 가져옵니다.

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에서 컴퓨트 분 및 스토리지 팩을 제외한 애드온 구매를 관리하는 데 사용됩니다.

여러 구독 애드온 구매 생성 (내부)#

POST 명령을 사용하여 여러 구독 애드온 구매를 생성, 업데이트 및 프로비저닝 해제합니다. 가능한 애드온 유형은 duo_pro, duo_enterprise, product_analytics입니다.

POST /internal/gitlab_subscriptions/namespaces/:id/subscription_add_on_purchases

지원 속성:

속성 타입 필수 여부 설명
quantity integer No 구독 애드온 구매의 단위 수. 음수가 아닌 정수여야 합니다. (예: GitLab Duo Pro 애드온의 시트 수)
started_on date Yes 구독 애드온 구매가 사용 가능하게 된 날짜
expires_on date Yes 구독 애드온 구매의 만료일
purchase_xid string No 구독 애드온 구매의 식별자 (예: Code Suggestions 애드온의 구독 이름)
trial boolean No 애드온이 평가판인지 여부

성공 시 201과 다음 응답 속성을 반환합니다:

속성 타입 설명
namespace_id integer 구매와 연관된 네임스페이스의 고유 식별자
namespace_name string 구매와 연결된 네임스페이스의 이름
add_on integer 구매와 관련된 애드온 유형. 가능한 애드온 유형은 Code Suggestions(GitLab Duo Pro의 별칭), Duo Enterprise, Product Analytics
quantity integer 구독 애드온에 대해 구매한 단위 수
started_on date 구독 애드온이 활성화된 날짜
expires_on date 구독 애드온이 만료될 날짜
purchase_xid string 구독 애드온 구매의 고유 식별자
trial boolean 애드온이 평가판의 일부인지 여부

생성/업데이트 요청 예시:

curl --request POST \
--header --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "quantity": 1, "started_on": "", "expires_on": "", "purchase_xid": "C-00123456", "trial": false }] } }' \
"https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases"

프로비저닝 해제 요청 예시:

curl --request POST \
--header --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{ "add_on_purchases": { "duo_pro": [{ "started_on": "", "expires_on": "" }] } }' \
"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": "C-00123456",
    "trial": false
  }
]

구독 애드온 구매 가져오기#

GET 명령을 사용하여 기존 구독 애드온 구매를 조회합니다.

GET /internal/gitlab_subscriptions/namespaces/:id/subscription_add_on_purchases/:add_on_name

요청 예시:

curl --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>" "https://gitlab.com/api/v4/internal/gitlab_subscriptions/namespaces/1234/subscription_add_on_purchases/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":"C-00123456",
  "trial":true
}

컴퓨트 분 프로비저닝#

컴퓨트 분 엔드포인트는 CustomersDot(customers.gitlab.com)에서 GitLab.com의 개인 네임스페이스 또는 최상위 그룹에 추가 컴퓨트 분 팩을 적용하는 데 사용됩니다.

추가 팩 생성#

POST 명령을 사용하여 추가 팩을 생성합니다.

POST /internal/gitlab_subscriptions/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/internal/gitlab_subscriptions/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": "C-00123456"
      }
    ]
  }'

응답 예시:

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "C-00123456"
  }
]

추가 팩 이동#

PATCH 명령을 사용하여 추가 팩을 한 네임스페이스에서 다른 네임스페이스로 이동합니다.

PATCH /internal/gitlab_subscriptions/namespaces/:id/minutes/move/:target_id
속성 타입 필수 여부 설명
id string yes 팩을 이전할 네임스페이스의 ID
target_id string yes 팩을 받을 타깃 네임스페이스의 ID

요청 예시:

curl --request PATCH \
  --url "http://localhost:3000/api/v4/internal/gitlab_subscriptions/namespaces/123/minutes/move/321" \
  --header "X-CUSTOMERS-DOT-INTERNAL-TOKEN: <json-web-token>"

응답 예시:

{
  "message": "202 Accepted"
}

더 이상 사용되지 않는 엔드포인트#

이 엔드포인트들은 내부 엔드포인트로 마이그레이션되었습니다. 현재 더 이상 사용되지 않으며 향후 마일스톤에서 제거될 예정입니다.

애드온 구매 (더 이상 사용되지 않음)#

이 API는 CustomersDot에서 컴퓨트 분 및 스토리지 팩을 제외한 애드온 구매를 관리하는 데 사용됩니다.

구독 애드온 구매 생성 (더 이상 사용되지 않음)#

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="C-00123456"&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":"C-00123456",
  "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="C-00123456"&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":"C-00123456",
  "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":"C-00123456",
  "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": "C-00123456"
      }
    ]
  }'

응답 예시:

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "C-00123456"
  }
]

추가 팩 이동 (더 이상 사용되지 않음)#

PATCH 명령을 사용하여 추가 팩을 한 네임스페이스에서 다른 네임스페이스로 이동합니다.

PATCH /namespaces/:id/minutes/move/:target_id
속성 타입 필수 여부 설명
id string yes 팩을 이전할 네임스페이스의 ID
target_id string yes 팩을 받을 타깃 네임스페이스의 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 yes 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 지난 한 달 동안의 최대 활성 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일
trial_ends_on date no 평가판 종료일

요청 예시:

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 no 구독 시작일
end_date date no 구독 종료일
plan_code string no 구독 티어 코드
seats integer no 구독의 시트 수
max_seats_used integer no 지난 한 달 동안의 최대 활성 사용자 수
auto_renew boolean no 종료일에 구독이 자동 갱신되는지 여부
trial boolean no 구독이 평가판인지 여부
trial_starts_on date no 평가판 시작일. trial이 true이면 필수.
trial_ends_on date no 평가판 종료일

요청 예시:

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
  }
}

구독 가져오기 (더 이상 사용되지 않음)#

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
  }
}