마켓플레이스 파트너

GitLab은 권한이 있는 채널 파트너에게 GitLab 제품의 판매를 처리하기 위해 선택된 유통 마켓플레이스에 자동화를 지원합니다. 마켓플레이스 파트너는 GitLab Marketplace API를 사용하여 자사 시스템을 GitLab과 통합하여 자사 사이트에서 GitLab 구독을 판매할 수 있습니다.

이 문서의 대상 독자는 마켓플레이스 파트너를 위한 제3자 개발자입니다.

마켓플레이스 API 작동 방식

마켓플레이스 API는 Customers Portal에 호스팅됩니다. Customers Portal을 통해 개별 고객이 GitLab 구독을 구매하고 관리할 수 있으며 파트너가 판매를 수행할 수 있도록 API를 지원합니다. Customers Portal은 Zuora 및 Salesforce를 포함한 다른 GitLab 서비스와 통합되어 작업 중심적 사용자 인터페이스를 제공합니다.

다음 예는 다음 구성요소 간의 일반 구매 흐름에 대한 요청과 응답을 보여줍니다.

고객
마켓플레이스 파트너 시스템
Customers Portal
Zuora
Salesforce

sequenceDiagram participant 고객 participant 마켓플레이스 파트너 시스템 participant Customers Portal participant Zuora participant Salesforce 고객 ->> 마켓플레이스 파트너 시스템: GitLab 구독을 구매하기 위한 주문 마켓플레이스 파트너 시스템 ->> Customers Portal: OAuth 토큰 받기 Customers Portal ->> 마켓플레이스 파트너 시스템: 액세스 토큰 마켓플레이스 파트너 시스템 ->> Customers Portal: 주문하기 Customers Portal ->> Zuora: Zuora 구독 생성 Customers Portal ->> Salesforce: Salesforce 객체 생성 Zuora ->> Customers Portal: Zuora 구독 데이터와 함께 성공 응답 Customers Portal ->> 마켓플레이스 파트너 시스템: 주문 ID와 함께 성공 응답 Zuora ->> Customers Portal: Zuora 호출 이벤트 Customers Portal ->> 고객: 라이선스 알림 보내기 마켓플레이스 파트너 시스템 ->> Customers Portal: 주문 상태 폴링 Customers Portal ->> 마켓플레이스 파트너 시스템: 주문 상태와 함께 성공 응답

마켓플레이스 API 명세

마켓플레이스 API의 OpenAPI 스펙은 마켓플레이스 대화형 API 문서에서 제공됩니다.

마켓플레이스 API 액세스

마켓플레이스 API에 액세스하려면 다음을 수행해야 합니다.

GitLab에서 액세스 요청
OAuth 액세스 토큰을 검색

마켓플레이스 API 엔드포인트는 OAuth 2.0으로 보호됩니다. OAuth는 HTTP 서비스의 리소스에 대한 제한된 액세스를 마켓플레이스 파트너 응용 프로그램과 같은 제3자나 클라이언트 응용 프로그램에 부여하는 인가 프레임워크입니다.

OAuth 2.0은 클라이언트 응용 프로그램이 액세스 토큰_으로 권한을 얻는 방식을 설명하는 _그랜트 타입 (또는 플로우)을 사용합니다. 액세스 토큰은 클라이언트 응용 프로그램이 리소스 서버에 권한이 있는 요청을 수행하는 데 사용하는 문자열입니다.

마켓플레이스 API는 client_credentials 그랜트 타입을 사용합니다. 클라이언트 응용 프로그램은 사용자 대신 자체 리소스에 액세스하는 데 액세스 토큰을 사용합니다.

단계 1: 액세스 요청

마켓플레이스 API를 사용하려면 먼저 마켓플레이스 파트너 매니저에게 연락하거나 partnerorderops로 이메일을 보내어 액세스를 요청해야 합니다. 액세스를 요청한 후, GitLab은 다음과 같은 계정 및 자격 증명을 구성합니다.

클라이언트 자격 증명. 마켓플레이스 API는 OAuth 2.0으로 보호됩니다. 클라이언트 자격 증명에는 액세스 토큰을 검색하는 데 필요한 클라이언트 ID와 클라이언트 시크릿이 포함됩니다.
Zuora 시스템의 소유자 계정. 청구 처리에 필요합니다.
Salesforce 시스템의 유통업체 계정.
Salesforce 시스템의 거래처 파트너 계정. GitLab은 거래처 ID를 통과할 수 있는 승인된 디렉터리에 거래처 파트너 ID를 추가합니다.

단계 2: 액세스 토큰 검색

액세스 토큰을 검색하려면,

다음 필수 매개변수를 사용하여 /oauth/token 엔드포인트에 POST 요청을 수행합니다.

매개변수	유형	필수	설명
`client_id`	문자열	예	Customers Portal의 클라이언트 응용 프로그램 레코드 ID. GitLab에서 받음.
`client_secret`	문자열	예	Customers Portal의 클라이언트 응용 프로그램 레코드 시크릿. GitLab에서 받음.
`grant_type`	문자열	예	자격 증명 플로우의 종류를 지정합니다. `client_credentials`를 사용합니다.
`scope`	문자열	예	액세스 레벨을 지정합니다. 읽기 전용 액세스에는 `marketplace.order:read`를 사용합니다. 만들기 액세스에는 `marketplace.order:create`를 사용합니다.

요청이 성공하면 응답 본문에 후속 요청에서 사용할 수 있는 액세스 토큰이 포함됩니다. 성공적인 응답 예에 대한 자세한 내용은 마켓플레이스 대화형 API 문서를 참조하십시오.

요청이 실패하면 응답 본문에 오류와 오류 설명이 포함됩니다. 오류는 다음과 같을 수 있습니다.

상태	설명
400	유효하지 않은 범위. `scope`가 `marketplace.order:read` 또는 `marketplace.order:create`인지 확인합니다.
401	잘못된 클라이언트. 클라이언트 특정 자격 증명에 오타나 추가 공백이 없는지 확인합니다. 올바르지 않은 `client_id` 또는 `client_secret`

단계 3: 액세스 토큰 사용

클라이언트 응용 프로그램에서 액세스 토큰을 사용하려면:

요청의 Authorization 헤더를 Bearer <your_access_token>으로 설정합니다.
엔드포인트에 필요한 매개변수나 데이터를 설정하고 요청을 보냅니다.

예시 요청:

curl \
  --url "https://customers.staging.gitlab.com/api/v1/marketplace/subscriptions/:external_subscription_id" \
  --header "Authorization: Bearer NHb_VhZhPOnBTSNfBSzmCmt28lLDWb2xtwr_c3DL148"

새로운 고객 구독 생성

마켓플레이스 파트너 클라이언트 응용 프로그램에서 새로운 고객 구독을 생성하려면,

다음 매개변수를 JSON 형식으로 customers.staging.gitlab.com의 /api/v1/marketplace/subscriptions 엔드포인트로 인가된 POST 요청을 수행합니다.

매개변수	유형	필수	설명
`externalSubscriptionId`	문자열	예	마켓플레이스 파트너 시스템의 구독 ID.
`tradingPartnerId`	문자열	예	Salesforce의 거래처 파트너 계정 ID. GitLab에서 받음.
`customer`	객체	예	고객에 대한 정보. 회사 이름이 포함되어야 합니다. 연락처에는 `firstName`, `lastName` 및 `email`이 포함되어야 합니다. 주소에는 `country`가 포함되어야 합니다.
`orderLines`	배열	예	구매한 제품을 지정합니다. `quantity` 및 `productId`를 포함해야 합니다.

요청이 성공하면 응답 본문에 새로 생성된 구독 번호가 포함됩니다. 전체 요청 본문의 예제에 대한 자세한 내용은 마켓플레이스 대화형 API 문서를 참조하십시오.

구독 생성이 실패하면 응답 본문에 오류 메시지와 오류 원인에 대한 세부 정보가 포함됩니다.

구독 상태 확인

특정 구독의 상태를 가져오려면,

Customers Portal의 /api/v1/marketplace/subscriptions/{external_subscription_id} 엔드포인트로 인가된 GET 요청을 수행합니다.

요청에는 상태를 가져오려는 구독의 마켓플레이스 파트너 시스템 ID를 포함해야 합니다.

요청이 성공하면 응답 본문에 구독 프로비전의 상태가 포함됩니다. 상태는 다음과 같을 수 있습니다.

생성 중
생성됨
실패
프로비저닝됨

전달된 external_subscription_id를 사용하여 구독을 찾을 수 없으면 응답이 404 Not Found 상태 코드를 포함합니다.