alicloud-network-esa

カテゴリー：サービス

Edge Security Acceleration（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 レコード、キャッシュルール、証明書など
• 分析 — トラフィック分析、時系列トレンド、Top-N ランキング、帯域幅統計、リクエスト指標

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

前提条件

• 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 は Edge Routine に基づくクイックデプロイフローで、HTML または静的ディレクトリをエッジにデプロイします。

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 を取得し、アクセスドメインとして使用します。

詳細については、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 の概要

• Namespace：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/AAAA（A ではありません）、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. 詳細取得 API／一覧 API で結果を確認します。
5. 繰り返し利用できるインベントリやサマリーが必要な場合は、scripts/ を使用し、出力を output/alicloud-network-esa/ に保存します。

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 サイトのトラフィックデータを照会・分析します。

主な機能

• 時系列データ：時間粒度を設定してトラフィックの傾向を照会します
• トップ N ランキング：国／IP／ホスト／パス／ステータスコードのディメンション別にランキングを取得します
• 複数のメトリクス：トラフィック、リクエスト数、リクエストトラフィック、ページビュー
• 豊富なディメンション：国、州、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 — トップ N ランキング

さまざまなディメンション別に、トップ 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 Code	Error Code	Description
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

一般的な操作の対応関係

サイト管理

• サイトの作成：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（正規表現）には標準プラン以上が必要です。
• エッジキャッシュ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（正規表現）
Basic	サポート	サポート	非対応
Standard	サポート	サポート	サポート
Enterprise	サポート	サポート	サポート

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

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

認証の設定（README に準拠）

環境変数：

export ALICLOUD_ACCESS_KEY_ID="your-ak"
export ALICLOUD_ACCESS_KEY_SECRET="your-sk"
export ALICLOUD_REGION_ID="cn-hangzhou"

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

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-ak"
export ALIBABA_CLOUD_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/alicloud-network-esa/

参考資料

Pages、ER、KV

• Pages デプロイメントリファレンス：references/pages.md
• Edge Routine リファレンス：references/er.md
• Edge KV Storage リファレンス：references/kv.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
• Top-N データ API：references/top-data.md
• メトリクスとディメンションのリファレンス：references/fields.md