GraphQLでのEnterpriseアカウントの管理について
Organizationをモニターし、変更を行ってコンプライアンスを維持しやすくするために、Enterprise Accounts API及びAudit Log APIを利用できます。これらはGraphQL APIでのみ利用できます。
Enterpriseアカウントのエンドポイントは、GitHub Enterprise Cloud及びGitHub Enterprise Serverのどちらでも動作します。
GraphQL を使用すると、指定したデータのみを要求し、返すことができます。 たとえば、組織に追加された新しい組織メンバーの情報をすべて表示するには、GraphQL クエリ (つまり情報の要求) を作成します。 また、Enterprise アカウントに管理者を招待するための変化 (変更) を加えることもできます。
Audit Log API を使用すると、次のような場合を監視できます。
- 組織またはリポジトリの設定にアクセスする。
- アクセス許可を変更する。
- 組織、リポジトリ、またはチームのユーザーを追加または削除する。
- ユーザーを管理者に昇格させる。
- GitHub アプリのアクセス許可を変更する。
Audit Log API を使用すると、監査ログ データのコピーを保持できます。 Audit Log APIで発行するクエリについては、GraphQLのレスポンスには最大で90から120日分のデータが含まれることがあります。 Audit Log API で使用できるフィールドの一覧については、「インターフェイス」を参照してください。
Enterprise APIを利用すると、以下のことができます。
- Enterpriseアカウントに属するすべてのOrganizationとリポジトリの取得と確認。
- Enterpriseアカウントの設定変更。
- EnterpriseアカウントとそのOrganizationに関する設定ポリシーの設定。
- Enterpriseアカウントへの管理者の招待。
- Enterpriseアカウント内での新しいOrganizationの作成。
エンタープライズ アカウント API で使用できるフィールドの一覧については、「Enterpriseアカウントの管理」を参照してください。
EnterpriseアカウントでGraphQLを使い始める
GraphQLを使ってEnterpriseアカウントの管理を始めるには、以下のステップに従ってください。
- personal access token で認証を行う
- GraphQLクライアントの選択もしくはGraphQL Explorerの利用
- GraphQL APIを利用するためのInsomniaのセットアップ
クエリの例については、「エンタープライズ アカウント API を使ったクエリの例」を参照してください。
1. personal access token で認証を行う
-
GraphQL で認証を行うには、開発者の設定から personal access token を生成する必要があります。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。
-
アクセスしたいエンタープライズの領域に対する personal access token に、管理者とフル コントロールのアクセス許可を付与します。 プライベート リポジトリ、Organization、Team、ユーザー データ、および Enterprise の課金とプロフィールのデータへのアクセスに対するフル アクセス許可の場合は、personal access token に対して次のスコープを選ぶことをお勧めします。
repo
admin:org
user
admin:enterprise
Enterpriseアカウントに固有にスコープは以下のとおりです。
admin:enterprise
: Enterprise のフル コントロールを付与します (manage_runners:enterprise
、manage_billing:enterprise
、read:enterprise
を含みます)manage_billing:enterprise
: Enterprise の課金データの読み取りと書き込み。manage_runners:enterprise
: GitHub Actions エンタープライズ ランナーとランナー グループを管理するためのアクセス。read:enterprise
: エンタープライズのプロファイル データを読み取ります。
-
personal access token をコピーし、GraphQL クライアントに追加するまで安全な場所に保管しておきます。
2. GraphQL クライアントの選択
GraphiQLもしくはベースURLの設定ができる他のスタンドアローンのGraphQLクライアントを使うことをおすすめします。
以下のGraphQLクライアントの利用を検討しても良いでしょう。
この次のステップではInsomniaを使います。
3. エンタープライズ アカウントで GitHub GraphQL API を使用するための Insomnia の設定
-
ベース URL と
POST
メソッドを GraphQL クライアントに追加します。 GraphQL を使用して情報の要求 (クエリ)、情報の変更 (ミューテーション)、または GitHub API を使用してデータを転送する場合、既定の HTTP メソッドはPOST
であり、ベース URL は次の構文に従います。- エンタープライズ インスタンスの場合:
https://<HOST>/api/graphql
- GitHub Enterprise Cloud の場合:
https://api.github.com/graphql
- エンタープライズ インスタンスの場合:
-
[認証] メニューを選択し、 [ベアラー トークン] をクリックします。 以前に別の認証方法を選択した場合、メニューには代わりにその方法ののラベルが付けられています ([基本認証] など)。
-
[TOKEN] フィールドに、前の手順の personal access token を入力します。
-
[ヘッダー] をクリックします。
-
[ヘッダー] タブの [追加] をクリックします。
-
[ヘッダー] フィールドに「
Content-Type
」と入力します。 -
[値] フィールドに「
application/json
」と入力します。
これでクエリを発行する準備ができました。
Enterprise Accounts APIを使ったクエリの例
この GraphQL クエリでは、Enterprise Accounts API を使用して、アプライアンスの各組織における public
リポジトリの合計数を要求します。 このクエリをカスタマイズするには、<enterprise-account-name>
をエンタープライズ アカウントのハンドルに置換します。 たとえば、エンタープライズ アカウントが https://github.com/enterprises/octo-enterprise
にある場合は、<enterprise-account-name>
を octo-enterprise
に置換します。
query publicRepositoriesByOrganization($slug: String!) {
enterprise(slug: $slug) {
...enterpriseFragment
}
}
fragment enterpriseFragment on Enterprise {
... on Enterprise{
name
organizations(first: 100){
nodes{
name
... on Organization{
name
repositories(privacy: PUBLIC){
totalCount
}
}
}
}
}
}
# Passing our Enterprise Account as a variable
variables {
"slug": "<enterprise-account-name>"
}
次の GraphQL クエリの例では、エンタープライズ アカウント API を使用せずに各組織の public
リポジトリの数を取得することがいかに困難であるかを示しています。 単一の変数だけをカスタマイズすれば済むようになることから、EnterpriseにとってGraphQLのEnterprise Accounts APIがこのタスクをシンプルにしてくれていることに注意してください。 このクエリをカスタマイズするには、<name-of-organization-one>
や <name-of-organization-two>
などを、インスタンスの組織名に置換します。
# Each organization is queried separately
{
organizationOneAlias: organization(login: "nameOfOrganizationOne") {
# How to use a fragment
...repositories
}
organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
...repositories
}
# organizationThreeAlias ... and so on up-to lets say 100
}
## How to define a fragment
fragment repositories on Organization {
name
repositories(privacy: PUBLIC){
totalCount
}
}
各Organizationに対して個別にクエリを行う
query publicRepositoriesByOrganization {
organizationOneAlias: organization(login: "<name-of-organization-one>") {
# How to use a fragment
...repositories
}
organizationTwoAlias: organization(login: "<name-of-organization-two>") {
...repositories
}
# organizationThreeAlias ... and so on up-to lets say 100
}
# How to define a fragment
fragment repositories on Organization {
name
repositories(privacy: PUBLIC){
totalCount
}
}
このGraphQLクエリは、EnterpriseのOrganizationの最新の5つのログエントリを要求します。 このクエリをカスタマイズするには、<org-name>
と <user-name>
を置換します。
{
organization(login: "<org-name>") {
auditLog(last: 5, query: "actor:<user-name>") {
edges {
node {
... on AuditEntry {
# Get Audit Log Entry by 'Action'
action
actorLogin
createdAt
# User 'Action' was performed on
user{
name
email
}
}
}
}
}
}
}
GraphQL の概要について詳しくは、「GraphQLの紹介」と「GraphQLでの呼び出しの作成」をご覧ください。
Enterprise Accounts APIでのGraphQLのフィールドと型
エンタープライズ アカウント API で使用できる新しいクエリ、ミューテーション、およびスキーマ定義型の詳細については、GraphQL リファレンス ページの詳細な GraphQL 定義が表示されているサイドバーを参照してください。
GitHub上のGraphQL Explorer内からリファレンスドキュメントにアクセスできます。 詳しくは、「Explorerの利用」を参照してください。 認証やレート制限の詳細など、その他の情報については「ガイド」を参照してください。