aliyun-esa-manage

Category: service

エッジセキュリティアクセラレーション（ESA）— Pages、Edge Routine、KV、サイト管理、分析など

Alibaba Cloud OpenAPI（RPC）と公式 Python SDK を使用して、ESA のすべての機能を管理します。

Alibaba Cloud ESA には、5 つの主要機能があります。

• Pages — HTML または静的ディレクトリをエッジノードにデプロイします（Edge Routine に基づく迅速なデプロイフロー）
• Edge Routine（ER） — サーバーレスエッジ関数のライフサイクル全体を管理します
• Edge KV — Namespace／Key／Value を管理する分散型エッジのキー・バリューストレージです
• サイト管理 — サイト、DNS レコード、キャッシュルール、証明書などを管理します
• 分析 — トラフィック分析、時系列トレンド、トップ N ランキング、帯域幅統計、リクエスト指標

ESA OpenAPI の呼び出しには、一貫して Python SDK を使用します。

前提条件

• AccessKey を用意します（最小権限の RAM ユーザー／ロール）。
• Python SDK をインストールします：pip install alibabacloud_esa20240910 alibabacloud_tea_openapi alibabacloud_credentials
• ESA OpenAPI は RPC 形式です。手動署名を避けるため、SDK または OpenAPI Explorer の使用を推奨します。

SDK クイックスタート

from alibabacloud_esa20240910.client import Client as Esa20240910Client
from alibabacloud_esa20240910 import models as esa_models
from alibabacloud_tea_openapi import models as open_api_models


def create_client(region_id: str = "cn-hangzhou") -> Esa20240910Client:
    config = open_api_models.Config(
        region_id=region_id,
        endpoint="esa.cn-hangzhou.aliyuncs.com",
    )
    return Esa20240910Client(config)

Pages — エッジページのデプロイ

Pages は、HTML または静的ディレクトリをエッジにデプロイする、Edge Routine に基づく迅速なデプロイフローです。

HTML ページのデプロイフロー

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(get access URL)

静的ディレクトリのデプロイフロー

CreateRoutine → CreateRoutineWithAssetsCodeVersion → Package zip and upload to OSS
→ Poll GetRoutineCodeVersionInfo(wait for available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(get access URL)

Zip パッケージの構成

Zip パッケージの構成は EDGE_ROUTINE_TYPE によって異なります（エントリーファイルとアセットディレクトリの有無に基づき、checkEdgeRoutineType が自動判定します）。

• JS_ONLY：routine/index.js（esbuild でバンドルするか、--no-bundle を指定してソースファイルを直接読み込みます）
• ASSETS_ONLY：assets/ 配下のすべての静的ファイル（元のディレクトリ構成を維持します）
• JS_AND_ASSETS：routine/index.js と assets/ の静的リソース（最も一般的な構成）

assets/ のパスは、設定内の assets.directory を基準とします。設定の優先順位：CLI 引数 > esa.jsonc／esa.toml。

主な注意事項

• 関数名の規則：小文字、数字、ハイフンを使用し、小文字で始めます。長さは 2 文字以上です
• 同名の関数：既存の関数を再利用し、新しいバージョンのコードをデプロイします
• デフォルトでは、ステージング環境と本番環境の両方にデプロイします
• デプロイ成功後、GetRoutine で defaultRelatedRecord を取得し、アクセスドメインとして使用します

カスタムドメインのバインド（CNAME アクセスサイト）

CNAME アクセスサイトでカスタムドメインを Pages／ER ルーティンにバインドするには、次の操作が必要です。

1. CreateRecord(A/AAAA, proxied=true)     → Register domain in ESA CDN
2. CreateRoutineRoute(rule expression)     → Route traffic to Edge Routine
3. External DNS: CNAME → record_cname      → Point domain to ESA CDN
4. ApplyCertificate(lets_encrypt)          → Provision SSL certificate

重要：CNAME アクセスサイトでは CreateRoutineRelatedRecord を使用しないでください。表示される DNS レコードが作成されず、CDN がオリジンにフォールバックします。代わりに、A／AAAA レコードと Route を使用してください。

SDK に関する注意：CreateRoutineRoute のパラメーターは route ではなく rule です（(http.host eq "domain") のような ESA ルール式）。

詳細は references/pages.md（「カスタムドメインのバインド」セクション）を参照してください。

Edge Routine（ER）— エッジ関数

Python SDK を使用して、サーバーレスエッジ関数のライフサイクル全体を管理します。

主なワークフロー

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion
→ (CreateRoutineRoute) → GetRoutine

API の概要

• 関数管理：CreateRoutine、DeleteRoutine、GetRoutine、GetRoutineUserInfo、ListUserRoutines
• コードバージョン：GetRoutineStagingCodeUploadInfo、CommitRoutineStagingCode、PublishRoutineCodeVersion、DeleteRoutineCodeVersion
• ルート：CreateRoutineRoute、UpdateRoutineRoute、DeleteRoutineRoute、GetRoutineRoute、ListRoutineRoutes、ListSiteRoutes
• 関連レコード：CreateRoutineRelatedRecord、DeleteRoutineRelatedRecord、ListRoutineRelatedRecords

ER コード形式

export default {
  async fetch(request) {
    return new Response("Hello", {
      headers: { "content-type": "text/html;charset=UTF-8" },
    });
  },
};

詳細は references/er.md を参照してください。

Edge KV — エッジのキー・バリューストレージ

分散型エッジのキー・バリューストレージです。Edge Routine から読み書きでき、OpenAPI／SDK でも管理できます。

主な概念

• Namespace：KV データの分離コンテナーです。Key の最大長は 512 文字、Value の最大サイズは 2MB（大容量の場合は 25MB）です
• TTL による有効期限をサポートします：Expiration（Unix タイムスタンプ）または ExpirationTtl（秒）

API の概要

• 名前空間：CreateKvNamespace、DeleteKvNamespace、GetKvNamespace、GetKvAccount、DescribeKvAccountStatus
• 単一キー操作：PutKv、GetKv、GetKvDetail、DeleteKv、PutKvWithHighCapacity
• バッチ操作：BatchPutKv、BatchDeleteKv、BatchPutKvWithHighCapacity、BatchDeleteKvWithHighCapacity、ListKvs

クイックスタート

client = create_client()

# Create namespace
client.create_kv_namespace(esa_models.CreateKvNamespaceRequest(namespace="my-ns"))

# Write
client.put_kv(esa_models.PutKvRequest(namespace="my-ns", key="k1", value="v1"))

# Read
resp = client.get_kv(esa_models.GetKvRequest(namespace="my-ns", key="k1"))

詳細なリファレンス：references/kv.md

サイト管理 — サイト管理

Python SDK を使用して、ESA サイト、DNS レコード、キャッシュルールなどを管理します。

API の動作に関する注意事項

• ほとんどのリスト API は、PageNumber と PageSize によるページネーションに対応しています。
• ListSites はすべてのリージョンのサイトを返すため、リージョンごとに反復処理する必要はありません。
• 新しく作成したサイトは pending 状態で開始します。有効化するには、VerifySite でアクセス検証を完了してください。
• サイトを削除すると、関連する設定もすべて削除されます。
• UpdateSiteAccessType で CNAME と NS を切り替えられますが、互換性のない DNS レコードが存在する場合、CNAME への切り替えに失敗することがあります。
• DNS レコード API（CreateRecord、ListRecords など）は、NS 接続サイトと CNAME 接続サイトの両方で動作します。CNAME サイトでは、使用できるタイプは CNAME と A/AAAA のみに制限され、レコードでアクセラレーションを無効にすることはできません（プロキシを有効のままにする必要があります）。
• DNS レコードの Type パラメーターには、正確な値を指定する必要があります。A ではなく A/AAAA を使用してください。指定できる値は CNAME、MX、TXT、NS、SRV、CAA です。
• CreateCacheRule は、2 種類の設定タイプに対応しています。global（サイト全体のデフォルト）と rule（一致式による条件付きルール）です。

ワークフロー

1. 対象サイトの ID、アクセス方式（CNAME/NS）、実行する操作を確認します。
2. references/api_overview.md で API グループと正確な操作名を確認します。
3. Python SDK（推奨）または OpenAPI Explorer で API を呼び出します。
4. describe/list API で結果を確認します。
5. 繰り返し使用するインベントリや概要が必要な場合は、scripts/ を使用し、出力を output/aliyun-esa-manage/ に保存します。

SDK の優先順位

1. Python SDK（推奨）
2. OpenAPI Explorer
3. その他の SDK（Python を利用できない場合のみ）

Python SDK スクリプト（インベントリ作成に推奨）

• ESA サイトをすべて一覧表示：scripts/list_sites.py
• プラン別にサイトを集計：scripts/summary_sites_by_plan.py
• サイトの状態を確認：scripts/check_site_status.py
• サイトの DNS レコードを一覧表示：scripts/list_dns_records.py

分析 — トラフィック分析

DescribeSiteTimeSeriesData API と DescribeSiteTopData API を使用して、ESA サイトのトラフィックデータを照会・分析します。

主な機能

• 時系列データ：設定可能な時間粒度でトラフィックの傾向を照会します
• Top-N ランキング：国、IP、ホスト、パス、ステータスコードのディメンション別にランキングを取得します
• 複数のメトリクス：トラフィック、リクエスト、RequestTraffic、PageView
• 豊富なディメンション：国、都道府県、ISP、ブラウザー、デバイス、ホスト、パス、ステータスコードなど

主な 2 つの API

1. DescribeSiteTimeSeriesData — 時系列の傾向

一定期間のトラフィック傾向を照会し、集計済みのデータポイントを返します。

時間粒度のルール：

時間範囲	間隔	間隔の値
<= 3 時間	1 分	60
3～12 時間	5 分	300
12 時間～1 日	15 分	900
1～10 日	1 時間	3600
10～31 日	1 日	86400

2. DescribeSiteTopData — Top-N ランキング

さまざまなディメンション別に Top-N ランキングデータを照会します。

上限の選択肢： 5、10、150

利用可能なメトリクス（FieldName）

フィールド	型	説明
Traffic	int	ESA からクライアントへのレスポンストラフィック（バイト）
Requests	int	リクエスト数
RequestTraffic	int	クライアントのリクエストトラフィック（バイト）
PageView	int	ページビュー数

利用可能なディメンション

地理的ディメンション： ClientCountryCode（国）、ClientProvinceCode（州）、ClientISP（ISP）、ClientASN

クライアント情報： ClientIP、ClientIPVersion、ClientBrowser、ClientDevice、ClientOS

リクエストの詳細： ClientRequestHost、ClientRequestMethod、ClientRequestPath、ClientRequestProtocol、ClientRequestQuery、ClientRequestReferer、ClientRequestUserAgent

レスポンス／キャッシュ： EdgeCacheStatus、EdgeResponseStatusCode、EdgeResponseContentType、OriginResponseStatusCode

その他： ALL（集計）、SiteId（アカウントレベルのクエリ）、Version、ClientSSLProtocol、ClientXRequestedWith

エラー処理

HTTP コード	エラーコード	説明
400	InvalidParameter.TimeRange	期間の上限を超えています（最大31日）
400	InvalidEndTime.Mismatch	EndTime が StartTime より前です
400	InvalidParameter.Field	無効なフィールド名です
400	InvalidParameter.Dimension	無効なディメンションです
400	InvalidTime.Malformed	時刻形式エラーです（yyyy-MM-ddTHH:mm:ssZ を使用してください）

詳細なリファレンス：references/time-series.md、references/top-data.md、references/fields.md

オリジンルール — CDN プロキシによるオリジンへの接続

Origin Rules は、ESA CDN がどのようにオリジンへ接続するかを制御します。ESA CDN を介してサブドメインをバックエンドサーバーにプロキシする場合に使用します。

CDN プロキシによるオリジン接続のワークフロー

CreateRecord(A, proxied=true) → ApplyCertificate → CreateOriginRule → 验证

API の概要

• Origin Rule の管理：CreateOriginRule、ListOriginRules、GetOriginRule、UpdateOriginRule、DeleteOriginRule

主なパラメーター

パラメーター	説明
rule	(http.host eq "sub.example.com") のような一致条件
origin_scheme	オリジンへの接続に使用するプロトコル：http または https（デフォルトは https）
origin_port	オリジンのポート
dns_record	オリジン接続先の DNS レコード名（ESA DNS レコード名である必要があります。IP は指定できません）

特に注意すべき点

1. dns_record は ESA DNS レコード名である必要があります（例：agent.example.com）。元の IP（例：1.2.3.4）は指定できません。指定すると destination_not_found が発生します。
2. origin_scheme のデフォルトは HTTPS です：オリジンサーバーが HTTP のみで待ち受けている場合は、明示的に http に設定する必要があります。設定しないと 502 エラーになります。
3. DNS レコードは proxied=true である必要があります：そうでない場合、トラフィックは CDN を経由せず、Origin Rule は適用されません。
4. Edge Routine Route は Origin Rule より優先されます：同じドメインに ER route がある場合、リクエストが遮断されるため、先に route を削除してください。

詳細なリファレンス：references/origin-rules.md

一般的な操作の対応表

サイト管理

• サイトの作成：CreateSite
• サイトの一覧表示：ListSites（SiteName、Status、AccessType、Coverage のフィルターに対応）
• サイトの詳細取得：GetSite
• サイトの削除：DeleteSite
• サイト名の利用可否確認：CheckSiteName
• サイトの所有権確認：VerifySite
• アクセスタイプの更新：UpdateSiteAccessType
• カバレッジの更新：UpdateSiteCoverage
• 現在のネームサーバーの取得：GetSiteCurrentNS
• カスタムネームサーバーの更新：UpdateSiteVanityNS
• サイトの一時停止／再開：UpdateSitePause、GetSitePause
• サイト名の排他設定：UpdateSiteNameExclusive、GetSiteNameExclusive
• バージョン管理：ActivateVersionManagement、DeactivateVersionManagement

サイト設定

• IPv6：GetIPv6、UpdateIPv6

DNS レコード

NS アクセス：すべてのレコードタイプに対応しています。CNAME アクセス：CNAME と A/AAAA のみ対応しており、プロキシは有効のままにする必要があります。

• レコードの作成：CreateRecord
• レコードの一覧表示：ListRecords（Type、RecordName、Proxied のフィルターに対応）
• レコードの取得：GetRecord
• レコードの更新：UpdateRecord
• レコードの削除：DeleteRecord
• レコードの一括作成：BatchCreateRecords
• レコードのエクスポート：ExportRecords

キャッシュルール

• キャッシュルールの作成：CreateCacheRule
• キャッシュルールの一覧表示：ListCacheRules
• キャッシュルールの取得：GetCacheRule
• キャッシュルールの更新：UpdateCacheRule
• キャッシュルールの削除：DeleteCacheRule

キャッシュルールの式に関する注意事項（重要）：

• CreateCacheRule のパラメーターはフラット形式であり、ネストされた JSON の Rule オブジェクトではありません。
• Rule パラメーターは、一致条件を表す式の文字列です。以下の ルール式の構文 セクションを参照してください。
• 簡単な注意点：ends_with()／starts_with() は関数呼び出し形式で指定する必要があります。matches（正規表現）には Standard プラン以上が必要です。
• エッジキャッシュ TTL は --EdgeCacheMode override_origin --EdgeCacheTtl <seconds> で設定します。

ルール式の構文

ESA では、複数の機能（キャッシュルール、WAF カスタムルール、レート制限、URL 書き換え、ヘッダー変更など）で統一されたルールエンジンの式構文を使用します。

使用する場面

一致条件式を受け付ける ESA API の Rule パラメーターには、この構文を使用します。

• CreateCacheRule / UpdateCacheRule - キャッシュルール
• CreateWafRule / UpdateWafRule - WAF カスタムルール
• CreateRatePlanRule - レート制限ルール
• CreateRewriteUrlRule / UpdateRewriteUrlRule - URL 書き換えルール
• オリジンルール、リダイレクトルール、ヘッダー変更ルールなど

式の形式

(condition)
(condition1 and condition2)
(condition1) or (condition2)

最大ネスト深度：2 階層。

演算子の構文 - 2 つの形式

中置形式（フィールドと値の間に演算子を配置）：

(field eq "value")
(field ne "value")
(field contains "value")
(field in {"value1" "value2"})
(field matches "regex")

関数形式（演算子でフィールドを囲む）：

(starts_with(field, "value"))
(ends_with(field, "value"))
(exists(field))
(len(field) gt 100)
(lower(field) eq "value")

よく使われるパターン

# Match file extension
--Rule '(http.request.uri.path.extension eq "html")'

# Match multiple extensions
--Rule '(http.request.uri.path.extension in {"js" "css" "png" "jpg"})'

# Match URL prefix
--Rule '(starts_with(http.request.uri, "/api/"))'

# Match URL suffix
--Rule '(ends_with(http.request.uri, ".html"))'

# Match URL containing substring (value MUST start with /)
--Rule '(http.request.uri contains "/test")'

# Match specific host
--Rule '(http.host eq "www.example.com")'

# Combined conditions
--Rule '(http.request.uri contains "/test" and ip.geoip.country eq "CN")'

# Match by country
--Rule '(ip.geoip.country eq "CN")'

# Exclude path
--Rule '(not starts_with(http.request.uri, "/admin/"))'

# Negating set membership
--Rule '(not http.host in {"a.com" "b.com"})'

主な注意点

1. ends_with と starts_with は、関数呼び出し構文を使用する必要があります。中置形式は使用できません。
2. matches（正規表現）にはスタンダードプラン以上が必要です。ベーシックプランでは RuleRegexQuotaCheckFailed が返されます。
3. URI に対して contains を使用する場合、パス区切り文字を含める必要があります。"/test" は正しいですが、"test" のみでは CompileRuleError が発生します。
4. in 演算子のリスト値は、中かっこの中でスペース区切りにします：{"a.com" "b.com"}。
5. 単一条件の場合、外側の括弧は省略可能です。
6. 「等しくない」には ne を使用します。not...eq は絶対に使用しないでください。
7. 集合に属することを否定する場合は、フィールドの前ではなく not...in を使用します。not in は使用しないでください。

プランの制限

プラン	eq/ne/in/starts_with/ends_with	contains	matches（正規表現）
ベーシック	対応	対応	非対応
スタンダード	対応	対応	対応
エンタープライズ	対応	対応	対応

AccessKey の優先順位（README に準拠）

1. 環境変数：ALIBABACLOUD_ACCESS_KEY_ID / ALIBABACLOUD_ACCESS_KEY_SECRET / ALIBABACLOUD_REGION_ID リージョンのポリシー：ALIBABACLOUD_REGION_ID は任意のデフォルト値です。設定されていない場合は、タスクに最も適したリージョンを選択してください。判断が難しい場合は、ユーザーに確認してください。
2. 共有設定ファイル：~/.alibabacloud/credentials（リージョンは引き続き環境変数から取得）

認証の設定（README に準拠）

環境変数：

export ALIBABACLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABACLOUD_ACCESS_KEY_SECRET="your-sk"
export ALIBABACLOUD_REGION_ID="cn-hangzhou"

Alibaba Cloud SDK でも次の方法がサポートされています：

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sk"

レガシーとの互換性：

export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"

共有設定ファイル：

~/.alibabacloud/credentials

[default]
type = access_key
access_key_id = your-ak
access_key_secret = your-sk

API の確認

• プロダクトコード：ESA
• デフォルトの API バージョン：2024-09-10
• メタデータエンドポイント：https://api.aliyun.com/meta/v1/products/ESA/versions/2024-09-10/api-docs.json
• OpenAPI メタデータエンドポイントを使用して、API の一覧表示とスキーマの取得を行います（参考資料を参照）。

出力ポリシー

レスポンスや生成した成果物を保存する必要がある場合は、次の場所に保存してください： output/aliyun-esa-manage/

参考資料

Pages、ER、KV

• Pages デプロイのリファレンス：references/pages.md
• Edge Routine のリファレンス：references/er.md
• Edge KV ストレージのリファレンス：references/kv.md

オリジンルール

• オリジンルールの設定とトラブルシューティング：references/origin-rules.md

サイト管理

• API の概要：references/api_overview.md
• エンドポイント：references/endpoints.md
• サイト：references/sites.md
• DNS レコード：references/dns-records.md
• キャッシュ：references/cache.md
• ソース：references/sources.md
• ルール式 - 生成ガイド：references/rule-generation-guide.md
• ルール式 - マッチフィールド：references/rule-match-fields.md
• ルール式 - 演算子：references/rule-operators.md
• ルール式 - 例：references/rule-examples.md

分析

• 時系列データ API：references/time-series.md
• 上位 N 件データ API：references/top-data.md
• メトリクスとディメンションのリファレンス：references/fields.md