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 で使用できるフィールドの一覧については、「AuditEntry インターフェイス」を参照してく� さい。

Enterprise APIを利用すると、以下のことができます。

Enterpriseアカウントに属するすべてのOrganizationとリポジトリの取得と確認。
Enterpriseアカウントの設定変更。
EnterpriseアカウントとそのOrganizationに関する設定ポリシーの設定。
Enterpriseアカウントへの管理者の招待。
Enterpriseアカウント内での新しいOrganizationの作成。

エンタープライズアカウント API で使用できるフィールドの一覧については、「エンタープライズアカウント API での GraphQL のフィールドと型」を参照してく� さい。

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 を作成する」をご覧く� さい。
アクセスしたい GHES の� �域に対する 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
認証するには、認証オプションメニューを開き、 [ベアラートークン] を選択します。次に、前にコピーした personal access token を追� します。
ヘッダー情� �を含めてく� さい。
- Content-Type をヘッダーとして、application/json を値として追� します。

これでクエリを発行する準備ができました。

Enterprise Accounts APIを使ったクエリの例

この GraphQL クエリは、エンタープライズアカウント 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のフィールドと型

Enterprise Accounts APIで利用できる新しいクエリ、ミューテーション、スキーマ定義された型の概要を以下に示します。

エンタープライズアカウント API で使用できる新しいクエリ、ミューテーション、およびスキーマ定義型の詳細については、GraphQL リファレンスページの詳細な GraphQL 定義が表示されているサイドバーを参照してく� さい。

GitHub上のGraphQL Explorer内からリファレンスドキュメントにアクセスできます。詳細については、「Explorer の利用」を参照してく� さい。認証やレート制限の詳細など、その他の情� �については「ガイド」を参照してく� さい。

この記事では、次の� �目が扱われます。