マーケットプレイスパートナー
GitLabは一部のディストリビューションマーケットプレイスにおいて、作成者であるチャネルパートナーへのGitLab製品の販売を処理するための自動化をサポートしています。マーケットプレイスパートナーはGitLabマーケットプレイスAPIを使用して、GitLabとシステムをインテグレーションし、そのサイトでGitLabサブスクリプションを販売することができます。
このドキュメントの対象読者は、マーケットプレイスパートナーのサードパーティ開発者です。
マーケットプレイスAPIの仕組み
Marketplace APIはCustomers Portalでホストされています。カスタマーズポータルでは、個人のお客様がGitLabサブスクリプションを購入・管理したり、パートナーがお客様に代わって販売を行うためのAPIをサポートしています。カスタマーポータルは、ZuoraやSalesforceを含むGitLabの他のサービスとインテグレーションし、ユーザーにタスク指向のインターフェースを提供します。
次の例は、以下のコンポーネント間のリクエストとレスポンスの典型的な購入フローを示しています：
- お客様
- マーケットプレイスパートナーシステム
- 顧客ポータル
- ズオラ
- Salesforce
マーケットプレイスAPI仕様
Marketplace API の OpenAPI 仕様は、Marketplace インタラクティブ API ドキュメントで入手できます。
Marketplace API にアクセス
Marketplace APIにアクセスするには、以下が必要です：
- GitLabにアクセスをリクエストします。
- OAuthアクセストークンを取得します。
Marketplace API エンドポイントはOAuth 2.0 でセキュリティ保護されています。OAuthは、マーケットプレイスのパートナーアプリケーションのようなサードパーティまたはクライアントアプリケーションに、カスタマーポータルのようなHTTPサービス上のリソースへの限定的なアクセスを許可する作成者フレームワークです。
OAuth 2.0では、クライアントアプリケーションが_アクセストークンの_形で認可を取得する方法を記述する_グラントタイプ_（または_フロー_）を使用します。アクセストークンは、クライアントアプリケーションがリソースサーバーに認可されたリクエストを行うために使用する文字列です。
Marketplace API では、client_credentials グラントタイプを使用します。クライアントアプリケーションは、ユーザーに代わってリソースにアクセスするのではなく、自身のリソースにアクセスするためにアクセストークンを使用します。
ステップ 1: アクセスのリクエスト
Marketplace APIを使用する前に、Marketplaceパートナーマネージャに連絡するか、partnerorderops にメールしてアクセスをリクエストする必要があります。アクセスをリクエストすると、GitLabは以下のアカウントと認証情報を設定します：
- クライアントの認証情報。Marketplace API は OAuth 2.0 でセキュリティ保護されています。クライアント認証情報には、OAuth アクセストークンを取得するために必要なクライアント ID とクライアントシークレットが含まれます。
- Zuora システムの請求書オーナーアカウント。請求書処理に必要です。
- Salesforce システムの販売代理店アカウント。
- Salesforce システムの取引先アカウント。GitLabはバリデーションをパスするために、取引先IDを許可リストに追加します。
ステップ2：アクセストークンの取得
アクセストークンを取得します、
- 以下の必須パラメータを指定して、
/oauth/tokenエンドポイントに POST リクエストを行います：
| パラメータ | 種類 | 必須 | 説明 |
|---|---|---|---|
client_id | 文字列です。 | yes | カスタマーポータルのクライアントアプリケーションレコードのID。GitLabから受信。 |
client_secret | 文字列です。 | yes | カスタマーズポータルのクライアントアプリケーションレコードのシークレット。GitLabから受け取りました。 |
grant_type | 文字列です。 | yes | クレデンシャルフローのタイプを指定します。client_credentials を使用します。 |
scope | 文字列です。 | yes | アクセス・レベルを指定します。読み取り専用アクセスにはmarketplace.order:read を使用します。作成アクセスにはmarketplace.order:create を使用します。 |
リクエストに成功すると、レスポンス本文に、以降のリクエストで使用できるアクセストークンが含まれます。成功したレスポンスの例については、Marketplace インタラクティブ 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"
新規顧客サブスクリプションの作成
マーケットプレイスパートナーのクライアントアプリケーションから新しい顧客サブスクリプションを作成するには、以下の手順に従います、
- Customers Portal の
/api/v1/marketplace/subscriptionsエンドポイントに、JSON 形式で以下のパラメータを指定して、作成者指定の POST リクエストを送信します：
| パラメータ | 種類 | 必須 | 説明 |
|---|---|---|---|
externalSubscriptionId | 文字列です。 | yes | マーケットプレイスパートナーシステム上のサブスクリプションのID。 |
tradingPartnerId | 文字列です。 | yes | Salesforce の取引先アカウントの ID。GitLabから受信。 |
customer | オブジェクトを返します。 | yes | 顧客に関する情報。会社名を含む必要があります。連絡先にはfirstName 、lastName 、emailを含めてください。アドレスにはcountryを含めてください。 |
orderLines | アレイ | yes | 購入した製品を指定します。quantity とproductId を含む必要があります。 |
リクエストが成功した場合、レスポンスボディには新しく作成された購読番号が含まれます。完全なリクエストボディの例については、Marketplace インタラクティブ API ドキュメントを参照してください。
サブスクリプションの作成が失敗した場合、レスポンスボディにはエラーの原因についての詳細を含むエラーメッセージが含まれます。
サブスクリプションのステータスの確認
指定したサブスクリプションのステータスを取得するには
- カスタマ・ポータルの
/api/v1/marketplace/subscriptions/{external_subscription_id}エンドポイントに作成者 GET リクエストを行います。
リクエストには、ステータスを取得するサブスクリプションのマーケットプレイス・パートナー・システムIDを含める必要があります。
リクエストに成功すると、レスポンスボディにサブスクリプションのステータスが含まれます。ステータスは次のとおりです：
- 作成中
- 作成
- 失敗
- プロビジョニング
渡されたexternal_subscription_id を使用してサブスクリプションが見つからない場合、レスポンスは 404 Not Found ステータスになります。