
# エンドポイント

Actuator のエンドポイントは、**有効**かつ**公開**されているときに HTTP で応答します。有効かどうかはエンドポイントがそもそも存在するかを決め、公開されているかどうかは HTTP がそれを見せるかを決めます。どちらも Spring Boot の `management.*` プロパティで設定し、エンドポイントは Web スターターのサーバーで `/actuator` の下に応答します。

## 使う理由

ヘルスチェックはロードバランサーから到達できなければなりませんが、アプリケーションのマッピングは他の誰にも関係のないものです。Spring Boot と同じく、デフォルトで `health` だけを公開することで、それ以外は自分で選ぶまで非公開に保たれます。

## 例

```yaml
# lib/resources/application.yml
management:
  endpoints:
    web:
      base-path: /manage                 # /actuator/health の代わりに /manage/health
      exposure:
        include: "*"                     # 有効なすべてのエンドポイント...
        exclude: mappings                # ...ただしマッピングは除く
      path-mapping:
        health: healthcheck              # /manage/healthcheck
      discovery:
        enabled: true
  endpoint:
    info:
      access: read-only
```

```properties
# lib/resources/application.properties: 同じ内容
management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=mappings
management.endpoints.web.path-mapping.health=healthcheck
management.endpoints.web.discovery.enabled=true
management.endpoint.info.access=read-only
```

```console
$ curl localhost:8080/manage/healthcheck
{"status":"UP"}
```

YAML では `"*"` を引用符で囲んでください。裸の `*` はエイリアスです。

## 有効

エンドポイントは、次のうち最初に設定されているものによって有効になります。

1. `management.endpoint.<id>.access`: `none` は無効にし、`read-only` と `unrestricted` は有効にします (Spring Boot 3.4 以降)。
2. `management.endpoint.<id>.enabled`: `true` または `false` (Spring Boot 2 と 3)。
3. `management.endpoints.access.default`: 自分の設定を持たないすべてのエンドポイントのアクセス。
4. `management.endpoints.enabled-by-default`。
5. エンドポイント自身のデフォルト: `@Endpoint(enableByDefault:)`。組み込みのものは `true`。

組み込みの ID は `health`、`info`、`mappings`、`jsonschemas`、`isolates`、`qps` です。`qps` エンドポイントは、Web スターターのデバッグ機能がビルドに入っているときにだけ存在します (`spring.web.debug.qps.enabled: true`、[毎秒のリクエスト数](qps.md) を参照)。

無効なエンドポイントは公開も列挙もされません。不明な `access` の値は起動を止めます (`must be one of none, read-only, unrestricted`)。今のところ読み取り操作しかないため、`read-only` と `unrestricted` は同じ意味です。

```properties
# すべて無効にしてから、health だけを再び有効にする。
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
```

## 公開

| キー | デフォルト | 意味 |
|---|---|---|
| `management.endpoints.web.exposure.include` | `health` | HTTP で公開する ID。すべてなら `*` |
| `management.endpoints.web.exposure.exclude` | なし | 公開しない ID、または `*`。`include` より優先される |

## パス

| キー | デフォルト | 意味 |
|---|---|---|
| `management.endpoints.web.base-path` | `/actuator` | エンドポイントを置くパス。`/` はディスカバリーページなしでルートに置く (`/health`)。先頭の `/` がなければ追加され、末尾のものは取り除かれる |
| `management.endpoints.web.path-mapping.<id>` | ID | 一つのエンドポイントの別のパス |
| `management.endpoints.web.discovery.enabled` | `true` | ベースパスが公開されたエンドポイントへのリンクを返すかどうか |

エンドポイントは、Web スターターの他のすべてのパスと同じく `server.context-path` の下にあります。別の管理用ポートはありません。

## ディスカバリーページ

`GET /actuator` は公開されたエンドポイントを列挙します。

```json
{"_links": {
  "self": {"href": "http://localhost:8080/actuator", "templated": false},
  "health": {"href": "http://localhost:8080/actuator/health", "templated": false},
  "health-path": {"href": "http://localhost:8080/actuator/health/{*path}", "templated": true},
  "info": {"href": "http://localhost:8080/actuator/info", "templated": false}}}
```

## メディアタイプとステータスコード

| リクエスト | 応答 |
|---|---|
| `Accept: application/vnd.spring-boot.actuator.v3+json`、`*/*`、またはなし | バージョン 3 の JSON、`application/vnd.spring-boot.actuator.v3+json` |
| `Accept: application/json` | 同じ JSON を `application/json` として |
| `Accept: application/vnd.spring-boot.actuator.v2+json` | バージョン 2 の JSON (ヘルスの各部分は `details` の下) |
| エンドポイントが返せない `Accept` | `406` |
| `GET` と `HEAD` 以外のメソッド | `405` |
| `null` を返す操作 | `404` |
| ないか変換できないクエリパラメーター | `400` |

## Spring (Java) との対応

キー、デフォルト、メディアタイプは同じです。Spring Boot はエンドポイントを JMX や別の `management.server.port` でも公開できます。ここでは、メインのサーバーでの HTTP だけです。

## 関連項目

- [ヘルス](health.md)
- [マッピング](mappings.md)
- [JSON Schemas](json-schemas.md)
- [isolate](isolates.md)
- [毎秒のリクエスト数](qps.md)
- [独自のエンドポイント](custom-endpoints.md)
- [セキュリティ](security.md)
- [すべてのプロパティ](properties.md)
