Enterpriseアカウントの管理

GraphQLでのEnterpriseアカウントの管理について

Organizationをモニターし、変更を行ってコンプライアンスを維持しやすくするために、Enterprise Accounts API及びAudit Log APIを利用できます。これらはGraphQL APIでのみ利用できます。

Enterpriseアカウントのエンドポイントは、GitHub Enterprise Cloud及びGitHub Enterprise Serverのどちらでも動作します。

GraphQLを利用すれば、指定したデータ� けをリクエストして返してもらうことができます。たとえば、GraphQLクエリを作成し、情� �をリクエストすることで、Organizationに追� された新しいメンバーを全員みることができます。あるいはミューテーションを行って変更をかけて、Enterpriseアカウントに管理者を招待できます。

Audit Log APIでは、誰かが以下のようなことをするのをモニターできます。

Organizationあるいはリポジトリの設定へのアクセス。
権限の変更。
Organization、リポジトリ、Teamへのユーザーの追� もしくは削除。
ユーザを管理者に昇� �。
GitHub Appの権限の変更。

Audit Log APIを使えば、Audit logのデータのコピーを保持できます。 Audit Log APIで発行するクエリについては、GraphQLのレスポンスには最大で90から120日分のデータが含まれることがあります。 Audit Log APIで利用できるフィールドのリストについては、「 AuditEntryインターフェース」を参照してく� さい。

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

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

Enterprise Accounts APIで利用できるフィールドのリストについては、「Enterprise Accounts APIのGraphQLフィールドと型」を参照してく� さい。

EnterpriseアカウントでGraphQLを使い始める

GraphQLを使ってEnterpriseアカウントの管理を始めるには、以下のステップに従ってく� さい。

個人アクセストークンでの認証
GraphQLクライアントの選択もしくはGraphQL Explorerの利用
GraphQL APIを利用するためのInsomniaのセットアップ

クエリの例については「Enterprise Accounts APIを使ったクエリの例」を参照してく� さい。

1. 個人アクセストークンでの認証

GraphQLで認証を受けるには、開発者の設定から個人アクセストークン（PAT）を生成しなければなりません。詳しい情� �については、「個人アクセストークンを作成する」を参照してく� さい。
アクセスしたいGHESの� �域に対して、管理及び完全なコントロール権限を個人アクセストークンに付与してく� さい。プライベートリポジトリ、Organization、Team、ユーザデータ、Enterpriseの支払い及びプロフィールデータへのアクセスについての完全な権限に関しては、個人アクセストークンに対して以下のスコープを選択することをおすすめします。
- repo
- admin:org
- ユーザ
- admin:enterprise
Enterpriseアカウントに固有にスコープは以下のとおりです。
- admin:enterprise: Gives full control of enterprises (includes manage_billing:enterprise and read:enterprise)
- manage_billing:enterprise: Read and write enterprise billing data.
- read:enterprise: Enterpriseのプロフィールデータの読み取り。
個人アクセストークンをコピーし、GraphQLクライアントに追� するまでは安全な� �所に保管しておいてく� さい。

2. GraphQLクライアントの選択

GraphiQLもしくはベースURLの設定ができる他のスタンドアローンのGraphQLクライアントを使うことをおすすめします。

以下のGraphQLクライアントの利用を検討しても良いでしょう。

この次のステップではInsomniaを使います。

3. EnterpriseアカウントでGitHub GraphQL APIを利用するためのInsomniaのセットアップ

GraphQLクライアントにベースURLとPOSTメソッドを追� してく� さい。 GraphQLを使って情� �をリクエスト（クエリ）したり、情� �を変更（ミューテーション）したり、GitHub APIを使ってデータを転送したりする� �合、デフォルトのHTTPメソッドはPOSTであり、ベースURLは以下の構文に従います。
- Enterpriseインスタンスの� �合は、https://<HOST>/api/graphql
- GitHub Enterprise Cloudの� �合は、https://api.github.com/graphql
認証を受けるには、認証オプションのメニューを開き、Bearer tokenを選択してく� さい。次に、先ほどコピーした個人アクセストークンを追� してく� さい。
ヘッダー情� �を含めてく� さい。
- ヘッダーとしてContent-Typeを、値としてapplication/jsonを追� してく� さい。

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

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

このGraphQLクエリは、Enterprise Accounts APIを使い、アプライアンス中の各Organization内のパブリックなリポジトリの総数を要求しています。 To customize this query, replace <enterprise-account-name> with the handle for your enterprise account. For example, if your enterprise account is located at https://github.com/enterprises/octo-enterprise, replace <enterprise-account-name> with octo-enterprise.

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # フラグメントの使い方
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... といったように最大でたとえば100個続く
}
# How to define a fragment
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

次のGraphQLクエリの例は、Enterprise Accounts APIを使わずに各Organization内のpublicなリポジトリの数を取得するのがいかに難しいかを示します。単一の変数� けをカスタマイズすれば済むようになることから、EnterpriseにとってGraphQLのEnterprise Accounts APIがこのタスクをシンプルにしてくれていることに注意してく� さい。このクエリをカスタマイズするには、<name-of-organization-one>や<name-of-organization-two>などを自分のインスタンス上のOrganization名で置き換えてく� さい。

# 各organizationに対して個別にクエリを実行
{
  organizationOneAlias: organization(login: "nameOfOrganizationOne") {
    # フラグメントの使い方
    ...repositories
  }
  organizationTwoAlias: organization(login: "nameOfOrganizationTwo") {
    ...repositories
  }
  # organizationThreeAlias ... といったように最大でたとえば100個続く
}

## フラグメントの定義方法
fragment repositories on Organization {
  name
  repositories(privacy: PUBLIC){
    totalCount
  }
}

各Organizationに対して個別にクエリを行う

query publicRepositoriesByOrganization {
  organizationOneAlias: organization(login: "<name-of-organization-one>") {
    # フラグメントの使用方法
    ...repositories
  }
  organizationTwoAlias: organization(login: "<name-of-organization-two>") {
    ...repositories
  }
  # organizationThreeAlias ... といったように最大でたとえば100個続く
}
# フラグメントの定義方法
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 {
# Audit Logのエントリを'Action'で取得
            action
            actorLogin
            createdAt
#  'Action'を実行したUser
           user{
              name
                email
            }
          }
        }
      }
    }
  }
}

GraphQLの使い始め方に関する詳しい情� �については「GraphQLの紹介」及び「GraphQLでの呼び出しの作成」を参照してく� さい。

Enterprise Accounts APIでのGraphQLのフィールドと型

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

Enterprise APIで利用できる新しいクエリ、ミューテーション、スキーマ定義された型に関する詳しい情� �については、任意のGraphQLリファレンスページの詳細なGraphQLの定義があるサイドバーを参照してく� さい。

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