API チュートリアル

このチュートリアルでは、プログラム可能な方法で自動化を可能にするCaddyの管理APIの使い方を説明します。

目標

🔲 デーモンの実行
🔲 Caddy に設定を与える
🔲 設定のテスト
🔲 アクティブな設定の置換
🔲 設定のトラバース
🔲 @id タグの使用

前提条件

基本的なターミナル/コマンドラインスキル
基本的な JSON の経験
caddy と curl が PATH に含まれていること

Caddy デーモンを起動するには、run サブコマンドを使用します。

caddy run

これは永遠にブロックされますが、何が実行されているのでしょうか？現時点では…何もありません。デフォルトでは、Caddy の設定（「config」）は空です。これは別のターミナルで管理APIを使用して確認できます。

curl localhost:2019/config/

設定を与えることで、Caddy を使用可能にできます。/load エンドポイントに POST リクエストを送信することでこれを行うことができます。HTTP リクエストと同様に、これを行う方法はたくさんありますが、このチュートリアルでは curl を使用します。

最初の設定

リクエストを準備するには、設定を作成する必要があります。Caddy の設定は、単なるJSON ドキュメント（またはJSON に変換できるもの）です。

これを JSON ファイルに保存します。

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

次に、アップロードします。

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

別の GET リクエストで、Caddy が新しい設定を適用したことを確認できます。

curl localhost:2019/config/

ブラウザでlocalhost:2015にアクセスするか、curl を使用して動作を確認します。

curl localhost:2015
Hello, world!

Hello, world!が表示されたら、おめでとうございます。動作しています！特に本番環境にデプロイする前に、設定が期待通りに動作することを確認することをお勧めします。

歓迎メッセージを「Hello world!」からもう少しやる気に満ちた「I can do hard things.」に変更しましょう。設定ファイルでこの変更を行い、ハンドラーオブジェクトが次のようになるようにします。

{
	"handler": "static_response",
	"body": "I can do hard things."
}

設定ファイルを保存し、同じ POST リクエストを再度実行して、Caddy のアクティブな設定を更新します。

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

念のため、設定が更新されたことを確認します。

curl localhost:2019/config/

ブラウザでページを更新するか（または curl を再度実行するか）してテストすると、感動的なメッセージが表示されます！

設定のトラバース

小さな変更のために設定ファイルをすべてアップロードする代わりに、Caddy の API の強力な機能を使用して、設定ファイルに触れることなく変更を行います。

リクエスト URI のパスを使用して、設定構造をトラバースし、メッセージ文字列のみを更新できます（クリップされている場合は右にスクロールしてください）。

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
	-H "Content-Type: application/json" \
	-d '"Work smarter, not harder."'

例として、同様の GET リクエストで動作を確認できます。

curl localhost:2019/config/apps/http/servers/example/routes

表示されるはずです

[{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]

重要な注意：これは明らかですが、元の設定ファイルにない変更を行うために API を使用すると、設定ファイルは古くなります。これを処理する方法はいくつかあります。

caddy run コマンドの --resume を使用して、最後にアクティブな設定を使用します。
設定ファイルの使用と API を通じた変更を混在させないでください。単一の真実の源を持ってください。
後続の GET リクエストでCaddy の新しい設定をエクスポートします（最初の 2 つのオプションよりも推奨されません）。

JSON で `@id` を使用

設定のトラバースは確かに便利です。しかし、パスは少し長すぎませんか？

ハンドラーオブジェクトに@id タグを付けて、アクセスしやすくできます。

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
	-H "Content-Type: application/json" \
	-d '"msg"'

これにより、ハンドラーオブジェクトにプロパティ "@id": "msg" が追加され、次のようになります。

{
	"@id": "msg",
	"body": "Work smarter, not harder.",
	"handler": "static_response"
}

その後、直接アクセスできます。

curl localhost:2019/id/msg

そして、より短いパスでメッセージを変更できます。

curl \
	localhost:2019/id/msg/body \
	-H "Content-Type: application/json" \
	-d '"Some shortcuts are good."'

そして、もう一度確認します。

curl localhost:2019/id/msg/body

@id タグの使用