Enterpriseアカウントの管理

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の利用」を参照してください。認証やレート制限の詳細など、その他の情報については「ガイド」を参照してください。

この記事の内容