Enterpriseアカウントの管理

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

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

エンタープライズアカウントエンドポイントは、GitHub Enterprise Cloud と GitHub Enterprise Server の両方で機能します。

GraphQL を使用すると、指定したデータのみを要求し、返すことができます。たとえば、組織に追加された新しい組織メンバーの情報をすべて表示するには、GraphQL クエリ (つまり情報の要求) を作成します。また、Enterprise アカウントに管理者を招待するための変化 (変更) を加えることもできます。

監査ログ API を使用すると、誰かが次のような操作を行ったタイミングを監視できます。

組織またはリポジトリの設定にアクセスする。
アクセス許可を変更する。
組織、リポジトリ、またはチームのユーザーを追加または削除する。
ユーザーを管理者に昇格させる。
GitHub アプリのアクセス許可を変更します。

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

エンタープライズアカウントAPIを利用すると、以下のことができます。

貴社のEnterpriseアカウントに属するすべての組織とリポジトリを列挙して確認してください。
Enterpriseアカウントの設定変更。
エンタープライズアカウントおよびその組織の設定のためのポリシーを構成します。
エンタープライズアカウントに管理者を招待する。
企業アカウント内で新しい組織を作成する。

Enterprise Accounts API で使用できるフィールドの一覧については、「Enterpriseアカウントの管理」を参照してください。

エンタープライズアカウントに GraphQL を使用するGetting started

GraphQL を使用してエンタープライズアカウントを管理し始めるには、GraphQL クライアントの使用を参照してください。

クエリの例については、「Enterprise アカウント API を使ったクエリの例」を参照してください。

1. personal access token で認証を行う

GraphQL で認証を行うには、開発者の設定から personal access token を生成する必要があります。詳細については、「個人用アクセストークンを管理する」を参照してください。
アクセスしたいエンタープライズの領域に対する personal access token に、管理者とフルコントロールのアクセス許可を付与します。プライベートリポジトリ、組織、チーム、ユーザーデータ、エンタープライズ課金データ、およびプロファイルデータへの完全なアクセス権を得るには、これらのスコープをpersonal access tokenに対して選択することをお勧めします。
- repo
- admin:org
- user
- admin:enterprise
Enterpriseアカウントに固有のスコープは以下のとおりです。 * admin:enterprise: Enterprise のフルコントロールを付与します (manage_runners:enterprise、manage_billing:enterprise、read:enterprise を含みます) * manage_billing:enterprise: 企業の請求データの読み取りと書き込み。 * manage_runners:enterprise: GitHub Actions エンタープライズランナーとランナーグループを管理するアクセス。 * read:enterprise: エンタープライズのプロファイルデータを読み取ります。
personal access token をコピーし、GraphQL クライアントに追加するまで安全な場所に保管しておきます。

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

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

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

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

3. Insomnia アプリケーションを、エンタープライズアカウントで GitHub GraphQL API を使用するように設定する

ベース URL と POST メソッドを GraphQL クライアントに追加します。 GraphQL を使用して情報 (クエリ)、変更情報 (変更)、または GitHub API を使用してデータを転送する場合、既定の HTTP メソッドは POST であり、ベース URL は次の構文に従います。
- エンタープライズインスタンスの場合: https://<HOST>/api/graphql
- GitHub Enterprise Cloud の場合: https://api.github.com/graphql
- GitHub Enterprise Cloud とデータ所在地の場合: https://api.SUBDOMAIN.ghe.com/graphql

[認証] メニューを選択し、 [ベアラートークン] をクリックします。以前に別の認証方法を選択した場合、メニューには代わりにその方法ののラベルが付けられています ([基本認証] など)。

       ![Insomnia の展開された [認証] メニューのスクリーンショット。 メニュー ラベル [認証] と [ベアラー トークン] オプションが濃いオレンジ色の枠線で囲まれています。](/assets/images/developer/graphql/insomnia-bearer-token-option.png)

「TOKEN」フィールドに、前の手順で取得したpersonal access tokenを入力します。

       ![Insomnia の [ベアラー] 認証設定のスクリーンショット。 [TOKEN] フィールドが濃いオレンジ色の枠線で囲まれています。](/assets/images/developer/graphql/insomnia-base-url-and-pat.png)

          **[ヘッダー]** をクリックします。

       ![Insomnia の設定タブのスクリーンショット。 [ヘッダー] タブが濃いオレンジ色の枠線で囲まれています。](/assets/images/developer/graphql/json-content-type-header.png)

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

[ヘッダー] フィールドに「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クエリは、企業組織の直近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 定義が表示されているサイドバーを参照してください。

GraphQL クライアント内から参照ドキュメントをaccessできます。詳細については、「GraphQL クライアントの使用」を参照してください。認証やレート制限の詳細など、その他の情報については、guidesを参照してください。

この記事で