Skip to main content

Enterpriseアカウントの管理

Enterpriseアカウントと、そのアカウントが所有するOrganizationをGraphQL APIで管理できます。

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 で認証を行う

  1. GraphQL で認証を行うには、開発者の設定から personal access token を生成する必要があります。 詳しくは、「個人用アクセス トークンを管理する」を参照してください。

  2. アクセスしたいエンタープライズの領域に対する personal access token に、管理者とフル コントロールのアクセス許可を付与します。 プライベート リポジトリ、Organization、Team、ユーザー データ、および Enterprise の課金とプロフィールのデータへのアクセスに対するフル アクセス許可の場合は、personal access token に対して次のスコープを選ぶことをお勧めします。

    • repo
    • admin:org
    • user
    • admin:enterprise

    Enterpriseアカウントに固有にスコープは以下のとおりです。

    • admin:enterprise: Enterprise のフル コントロールを付与します (manage_runners:enterprisemanage_billing:enterpriseread:enterprise を含みます)
    • manage_billing:enterprise: Enterprise の課金データの読み取りと書き込み。
    • read:enterprise: エンタープライズのプロファイル データを読み取ります。
  3. personal access token をコピーし、GraphQL クライアントに追加するまで安全な場所に保管しておきます。

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

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

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

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

3. エンタープライズ アカウントで GitHub GraphQL API を使用するための Insomnia の設定

  1. ベース URL と POST メソッドを GraphQL クライアントに追加します。 GraphQL を使用して情報の要求 (クエリ)、情報の変更 (ミューテーション)、または GitHub API を使用してデータを転送する場合、既定の HTTP メソッドは POST であり、ベース URL は次の構文に従います。

    • エンタープライズ インスタンスの場合: https://<HOST>/api/graphql
    • GitHub Enterprise Cloud の場合: https://api.github.com/graphql
  2. [認証] メニューを選択し、 [ベアラー トークン] をクリックします。 以前に別の認証方法を選択した場合、メニューには代わりにその方法ののラベルが付けられています ([基本認証] など)。 Insomnia の展開された [認証] メニューのスクリーンショット。 メニュー ラベル [認証] と [ベアラー トークン] オプションが濃いオレンジ色の枠線で囲まれています。

  3. [TOKEN] フィールドに、前の手順の personal access token を入力します。 Insomnia の [ベアラー] 認証設定のスクリーンショット。 [TOKEN] フィールドが濃いオレンジ色の枠線で囲まれています。

  4. [ヘッダー] をクリックします。 Insomnia の設定タブのスクリーンショット。 [ヘッダー] タブが濃いオレンジ色の枠線で囲まれています。

  5. [ヘッダー] タブの [追加] をクリックします。

  6. [ヘッダー] フィールドに「Content-Type」と入力します。

  7. [値] フィールドに「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のフィールドと型

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

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

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