mabl APIでワークスペースとユーザーを管理する

mabl APIを使用すると、ワークスペースのプロビジョニング、メンバーシップの最新化、未使用のライセンスの回収、監査用のレポートダッシュボードの構築を行えます。いずれもUIを1つずつ操作する必要はありません。

この記事では、mabl APIでワークスペースとユーザーを管理する際の、代表的な目的ごとに手順を説明します。

• ワークスペースをプロビジョニングする
• メンバーのオンボーディングとオフボーディング
• ワークスペースの名前を変更する
• 未使用のライセンスを回収する
• アクティビティとシートを監視する
• ワークスペースの一覧を把握する
• ワークスペースを廃止する

始める前に

この記事で扱うエンドポイントは会社スコープです。会社が所有するすべてのワークスペースを対象に動作するため、ワークスペースのキーではなく、会社スコープのAPIキーを使用します。会社スコープのキーは、アカウント管理者がアカウントダッシュボードの [APIキー] タブから作成します。詳しい手順については、APIキーの管理をご覧ください。

この記事で扱う目的は、次の2種類の会社APIキーでカバーされます。

• ワークスペースライフサイクル: ワークスペースのプロビジョニング、名前の変更、廃止
• ユーザー管理: メンバーのオンボーディングとオフボーディング、未使用のライセンスの回収、アクティビティとシートの監視、ワークスペースの一覧の把握

また、いくつかの識別子が必要です。

• 会社IDとアカウントID: 会社レベルおよびアカウントレベルのエンドポイントには、それぞれのIDが必要です。アカウントダッシュボードの [会社のAPIキー] タブで [アカウントIDを表示] をクリックすると取得できます。
• ワークスペースID: ワークスペースレベルのエンドポイントにはワークスペースIDが必要です。アプリの [ワークスペース] > [ワークスペース] から取得できます。
• ユーザーID: メンバーシップエンドポイントが対象とするユーザーIDは、ユーザーのクエリーエンドポイントを使用して調べます。

ワークスペースをプロビジョニングする

製品、チーム、クライアントごとにワークスペースを分けているチームでは、ワークスペースの作成を手作業ではなく、オンボーディングプロセスのスクリプト化されたステップにできます。

• ワークスペースを作成する: /companies/{company_id}/workspaces に POST リクエストを送信します。ワークスペース名と所属するアカウントを指定し、owner_user_ids で所有者を割り当てます。

所有者は、会社のいずれかのmablワークスペースのメンバーである必要があります。そのため、新しいチーム向けにワークスペースを作成するプロビジョニングスクリプトでは、先に所有者のユーザーIDが必要です。ユーザーIDは、下記のメンバーのオンボーディングとオフボーディングで説明するとおり、ユーザーのクエリーエンドポイントで調べます。

作成時にクレジット割り当てを設定する

POST /companies/{company_id}/workspaces は credit_allocation と enforce_credit_limit を受け付けます。これらは、アカウントダッシュボードからワークスペースを追加するときに設定できる2つの項目と同じです。プロビジョニングスクリプトで作成時にクレジットの上限を指定すれば、誰かが上限を設定するまで新しいワークスペースがアカウントの共有プールを消費し続けることを避けられます。

上限の適用には割り当てが必要です。credit_allocation を指定せずに enforce_credit_limit を設定しても、適用する上限がありません。アカウント内の複数のワークスペース間で割り当てがどのように作用するかについては、クレジット割り当ての仕組みをご覧ください。

メンバーのオンボーディングとオフボーディング

これらのエンドポイントをIDツールやHRツールと連携することで、メンバーの参加、チーム異動、退職に合わせて、ワークスペースのメンバーシップを最新の状態に保てます。

• メンバーのロールを変更する: /workspaces/{workspace_id}/users/{id} に PATCH リクエストを送信し、新しいロール（所有者、編集者、または閲覧者）を指定します。チームメンバーのロールが変わるときに役立ちます。たとえば、ワークスペースを引き継ぐ編集者を所有者に昇格させる場合などです。
• メンバーを削除する: /workspaces/{workspace_id}/users/{id} に DELETE リクエストを送信します。オフボーディングのプロセスに組み込むと、メンバーの退職時にアクセス権が自動的に取り消されます。

どちらのエンドポイントも If-Match ヘッダーをサポートしているため、同時に行われた更新が互いを上書きすることはありません。また、どちらもワークスペースの最後の所有者が降格または削除されないように保護します。これにより、自動オフボーディングによってワークスペースの所有者が誤って不在になることを防げます。

ワークスペースの名前を変更する

• ワークスペースの名前を変更する: /workspaces/{workspace_id} に新しい名前を指定して PATCH リクエストを送信します。組織変更のあとにワークスペース名を命名規則に合わせ直す場合や、アプリで1つずつ開くのではなく複数のワークスペースをまとめて変更する場合に便利です。

未使用のライセンスを回収する

回収できるライセンスを見つけるには、各ワークスペースを手作業で確認するのではなく、アカウントレベルから始めます。

• アカウントユーザーの一覧を取得する: GET /accounts/{account_id}/users を呼び出すと、アカウント内のすべてのワークスペースのユーザーが、重複を除外したうえでアカウント単位のロールとともに一覧表示されます。inactive フィルターを追加すると、最近アクティビティのないユーザーのみが返されます。デフォルトでは「最近」は過去90日間を指します。任意の lookback_days パラメータを設定すると、この期間を広げたり狭めたりできます。
• アカウントユーザーを取得する: 対応する前に候補を確認するには、GET /accounts/{account_id}/users/{id} で個々のユーザーを調べます。または、GET /accounts/{account_id}/users/{id}/activity で、最終アクティビティ日時、アクション総数、ワークスペースごとの内訳を確認します。

ユーザーがアクセス権を必要としないことを確認したら、アカウントレベルのユーザーダッシュボードから削除するか、上記のオフボーディング用エンドポイントを使用して削除します。

アクティビティとシートを監視する

mablは、各ユーザーをテスト作成アクティビティに基づいてオートメーターまたは参加者に分類します。これらのエンドポイントを使用して、その内訳を追跡し、シートの割り当てを実際の使用状況に合わせることができます。

• アカウントのシート割り当てと使用状況: GET /accounts/{account_id}/seats を呼び出すと、割り当て済み、使用中、利用可能なシート数のスナップショットを、オートメーターと参加者に分けて取得できます。
• アカウントのユーザーごとのシート使用状況: さらに詳しく確認するには、GET /accounts/{account_id}/seats/usage を呼び出して、指定した月のユーザーごとのシート使用状況を取得します。各ユーザーはオートメーターまたは参加者に分類されます。これを定期的なレポートに取り込むことで、オートメーターと参加者の比率を継続的に把握し、手動での監査なしでアカウントを適正な規模に調整できます。

ワークスペースの一覧を把握する

• 会社内のワークスペースの一覧を取得する: 会社全体を把握するには（ガバナンスダッシュボードの構築や、他のエンドポイントが対象とするワークスペースIDの確認のために）、GET /companies/{id}/workspaces を呼び出します。会社内のすべてのワークスペースが、所有するアカウントごとにグループ化されて返されます。

ワークスペースを廃止する

• ワークスペースを削除する: /workspaces/{workspace_id} に DELETE リクエストを送信します。

詳細情報

各エンドポイントのリクエストとレスポンスの詳細については、mabl APIリファレンスを参照してください。