Конечные точки REST API для управления GitHub Enterprise Server

Сведения об API управления данными GitHub Enterprise Server

Вы можете управлять ваш экземпляр GitHub Enterprise Server с помощью API управления GitHub Enterprise Server . Например, можно получить сведения о версии программного обеспечения GitHub Enterprise Server на экземпляре или на экземплярах с несколькими узлами, просмотреть состояние реплика.

Укажите номер порта при вызове API конечных точек для API Управления api GitHub Enterprise Server API. Если экземпляр использует TLS, номер порта равен 8443. В противном случае номер порта равен 8080. Если вы не можете указать номер порта, необходимо настроить клиент для автоматического выполнения перенаправлений. Дополнительные сведения см. в разделе Настройка TLS.

Можно также использовать расширение {variables.product.prodname_cli% данных variables.product.prodname_ghe_server %} для вызова конечных точек в API управления GitHub Enterprise Server. Дополнительные сведения см. в репозитории github/gh-es.

Проверка подлинности

Чтобы проверить подлинность запросов к конечным точкам для API управления GitHub Enterprise Server укажите пароль для учетной записи администратора корневого сайта экземпляра в качестве маркера проверки подлинности. Используйте стандартную проверку подлинности HTTP для отправки пароля. Пользователь api_key определяет корневого администратора сайта. В следующем примере показана проверка подлинности для этого API. Замените ROOT-SITE-ADMINISTRATOR-PASSWORD паролем и ADMINISTRATION-PORT либо 8443, либо 8080.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Проверка подлинности в качестве пользователя Консоль управления

Учетные записи пользователей Консоль управления также могут проходить проверку подлинности для доступа к этим конечным точкам. Дополнительные сведения см. в разделе Управление доступом к консоли управления.

Для проверки подлинности с помощью пароля для учетной записи пользователя Консоль управления используйте стандартную проверку подлинности HTTP. В следующем примере замените YOUR_USER_NAME и YOUR_PASSWORD именем пользователя и паролем учетной записи.

curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage'

Параметры запроса

По умолчанию ответ содержит сведения обо всех настроенных узлах для экземпляра. В экземпляре с несколькими узлами данные, полученные из /data/user/common/cluster.conf. Чтобы отфильтровать ответ по конкретным узлам, можно использовать следующие параметры запроса.

Параметр запроса	Description
`uuid`	Уникальный идентификатор узла.
`cluster_role`	Для узлов в кластере роли, которые применяются к узлу. Дополнительные сведения см. в разделе "[AUTOTITLE)(/admin/enterprise-management/configuring-кластеризация/about-cluster-nodes)."

Можно указать несколько значений для параметра запроса, разделив значения запятой. Например, следующий запрос использует curl для возврата всех узлов с web-server ролью или storage-server ролью.

curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage/v1/config/nodes?cluster_role=WebServer,StorageServer'

Get GHES node metadata for all nodes

Get node metadata for all configured nodes in the current cluster. For more information, see "About clustering."

Параметры для "Get GHES node metadata for all nodes"

Параметры запроса
Имя., Тип, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get GHES node metadata for all nodes"

Код состояния	Описание
`200`	OK
`401`	Unauthorized
`500`	Internal error

Примеры кода для "Get GHES node metadata for all nodes"

Пример запроса

get/manage/v1/config/nodes

curl -L \
  -u "api_key:your-password" \
  http(s)://HOSTNAME/manage/v1/config/nodes

Response

Status: 200

{
  "topology": "Cluster",
  "nodes": [
    {
      "hostname": "data1",
      "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
      "cluster_roles": [
        "ConsulServer",
        "ElasticsearchServer",
        "GitServer",
        "StorageServer"
      ]
    },
    {
      "hostname": "data2",
      "uuid": "228406d4-f97c-11ed-ab01-062281bbcf03",
      "cluster_roles": [
        "ElasticsearchServer",
        "StorageServer",
        "PagesServer"
      ]
    }
  ]
}

Get the status of maintenance mode

Gets the status and details of maintenance mode on all available nodes. For more information, see "Enabling and scheduling maintenance mode."

Параметры для "Get the status of maintenance mode"

Параметры запроса
Имя., Тип, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get the status of maintenance mode"

Код состояния	Описание
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Примеры кода для "Get the status of maintenance mode"

Пример запроса

get/manage/v1/maintenance

curl -L \
  -u "api_key:your-password" \
  http(s)://HOSTNAME/manage/v1/maintenance

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "status": "scheduled",
    "scheduled_time": "2006-01-02T15:04:05+00:00",
    "connection_services": [
      {
        "name": "git operations",
        "number": 15
      },
      {
        "name": "mysql queries",
        "number": 6
      },
      {
        "name": "resque jobs",
        "number": 10
      },
      {
        "name": "aqueduct jobs",
        "number": 0
      }
    ],
    "can_unset_maintenance": true,
    "ip_exception_list": [
      "1.1.1.1"
    ],
    "maintenance_mode_message": "Scheduled maintenance for upgrading."
  }
]

Set the status of maintenance mode

Sets or schedules the maintenance mode. For more information, see "Enabling and scheduling maintenance mode."

Параметры для "Set the status of maintenance mode"

Параметры запроса
Имя., Тип, Description
`enabled` boolean Обязательное поле Whether to enable maintenance mode.
`uuid` string The UUID of the node to target. This parameter is incompatible with maintenance mode scheduling. Only use `uuid` if the value of `when` is empty or `now`.
`when` string The time to enable maintenance mode. If this parameter is empty or set to `now`, maintenance mode is enabled immediately. Otherwise, maintenance mode is enabled at the specified time. The format is ISO 8601.
`ip_exception_list` array of strings The list of IP addresses to exclude from maintenance mode. IPv4, IPv6, and CIDR addresses are supported.
`maintenance_mode_message` string The message to display to users when maintenance mode is enabled.

Коды состояния http-ответа для "Set the status of maintenance mode"

Код состояния	Описание
`200`	OK
`400`	Bad request
`401`	Unauthorized
`500`	Internal error

Примеры кода для "Set the status of maintenance mode"

Пример запроса

post/manage/v1/maintenance

curl -L \
  -X POST \
  -u "api_key:your-password" \
  http(s)://HOSTNAME/manage/v1/maintenance \
  -d '{"enabled":true,"when":"2006-01-02T15:04:05+00:00","ip_exception_list":["192.168.1.0/24","1.1.1.1"]}'

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "uuid": "1b6cf518-f97c-11ed-8544-061d81f7eedb",
    "message": "maintenance mode scheduled with exception list [1.1.1.1]"
  }
]

Get the status of services running on all replica nodes

Gets the status of all services running on each replica node. This endpoint may take several seconds to reply.

Параметры для "Get the status of services running on all replica nodes"

Параметры запроса
Имя., Тип, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get the status of services running on all replica nodes"

Код состояния	Описание
`200`	OK
`401`	Unauthorized
`500`	Internal error

Примеры кода для "Get the status of services running on all replica nodes"

Пример запроса

get/manage/v1/replication/status

curl -L \
  -u "api_key:your-password" \
  http(s)://HOSTNAME/manage/v1/replication/status

Response

Status: 200

{
  "status": "OK",
  "nodes": [
    {
      "hostname": "ghe-local-primary",
      "status": "OK",
      "services": []
    },
    {
      "hostname": "ghe-local-replica",
      "status": "OK",
      "services": [
        {
          "status": "OK",
          "name": "redis",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "elasticsearch",
          "details": "cluster is in sync (0 shards initializing, 0 shards unassigned)"
        },
        {
          "status": "OK",
          "name": "git",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "pages",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "alambic",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "git-hooks",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "consul",
          "details": "replication is in sync"
        },
        {
          "status": "OK",
          "name": "mysql",
          "details": "replication is in sync"
        }
      ]
    }
  ]
}

Get all GHES release versions for all nodes

Gets the GitHub Enterprise Server release versions that are currently installed on all available nodes. For more information, see "GitHub Enterprise Server releases."

Параметры для "Get all GHES release versions for all nodes"

Параметры запроса
Имя., Тип, Description
`uuid` string The UUID which identifies a node.
`cluster_roles` string The cluster roles from the cluster configuration file.

Коды состояния http-ответа для "Get all GHES release versions for all nodes"

Код состояния	Описание
`200`	OK
`401`	Unauthorized
`500`	Internal error

Примеры кода для "Get all GHES release versions for all nodes"

Пример запроса

get/manage/v1/version

curl -L \
  -u "api_key:your-password" \
  http(s)://HOSTNAME/manage/v1/version

Response

Status: 200

[
  {
    "hostname": "ghe-local-primary",
    "version": {
      "version": "3.9.0",
      "platform": "azure",
      "build_id": "fc542058b5",
      "build_date": "2023-05-02"
    }
  }
]