AEM Edge Functions aem-edge-functions

AEM Edge Functionsでは、JavaScriptをCDN レイヤーで実行し、データ処理をエンドユーザーに近づけることができます。 これにより、遅延を低減し、コンテンツの配信元を何度も訪問することなく、レスポンシブでダイナミックなエクスペリエンスを提供できます。

一般的なユースケースを次に示します。

AEM Edge Functionsは、AEM Sitesのお客様向けに、Edge Delivery ServicesとAEM as a Cloud Service Java スタックの両方と互換性があります。

このチュートリアル ​に従って、Edge Delivery ServicesとAEM as a Cloud Serviceの両方のJava スタックのバリエーションを具体的に説明します。

主なメリット key-benefits

前提条件 prerequisites

セットアップ setup

Adobe CLIのインストール install-adobe-cli

Adobe Developer CLI （aio）をインストールします。

npm install -g @adobe/aio-cli

AEM Edge Functions プラグインをインストールします。

aio plugins install @adobe/aio-cli-plugin-aem-edge-functions

環境のプラグインを認証して設定します。

aio login
aio aem edge-functions setup

setup コマンドを使用すると、ログインして、AEM Edge Functionsを使用するAEM環境を選択するように求められます。

Boilerplateの複製 boilerplate

aem-edge-functions-boilerplateを独自のリポジトリにコピーしてから、依存関係をインストールします。

npm install

AEM Edge機能の登録 register-your-function

AEM Edge関数は、YAML設定ファイルで宣言され、Cloud Manager設定パイプラインを通じてデプロイされます。

​1. 設定パイプラインの設定 configuration-pipeline

エッジ関数を作成する前に、Cloud Managerに環境のコンフィギュレーションパイプラインが存在することを確認します（AEM Java スタックを使用している場合）。または、プロジェクトがEdge Delivery Servicesで実装されている場合は、Edge Delivery Services パイプラインが存在することを確認します。 パイプラインの設定について詳しくは、設定パイプラインの使用を参照してください。

​2. Edge関数の宣言 declare-functions

設定ディレクトリにedgeFunctions.yamlという名前のファイルを作成します。

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
    # add advanced configuration under here

Java スタック環境には1つのエッジ関数があり、Edge Delivery Servicesの実装には3つのエッジ関数があります。 オプションのトップレベルキーは次のとおりです。

以下の詳細設定セクション ​のconfigs、secrets、kvsなどの詳細設定を参照してください。

​3. Cloud Managerを使用したEdge機能のデプロイ deploy-functions-via-cm

Cloud Managerを使用して、エッジ関数がCDNに登録されるようにパイプラインをデプロイします。

AEM Edge関数コードの作成、ビルド、デプロイ build-deploy

作成者 author

​ ボイラープレートのsrc フォルダーを出発点として使用して、エッジ関数コードビジネスロジックを記述します。

ビルド build

デプロイメント用にEdge関数コードをパッケージ化します。

aio aem edge-functions build

デプロイ deploy

パッケージ化されたエッジ関数コードを、指定されたエッジ関数にデプロイします。 function-name引数はedgeFunctions.yamlのname値と一致する必要があります：

aio aem edge-functions deploy <function-name>

テスト test

エッジ関数が期待どおりに機能することを確認します。 テストは次の場所で実施できます。

edgefunction-pXXXXX-eYYYYY-<function name>.adobeaemcloud.com/<path>

例えば、AEM Java スタックの場合：

edgefunction-pXXXXX-eYYYYY-my-edge-function.adobeaemcloud.com/weather

またはEdge Delivery Servicesの場合：

edgefunction-pXXXXX-dYYYYY-my-edge-function.adobeaemcloud.com/weather

edgefunction​というプレフィックスが付いたこのドメインは、デバッグ用のみですが、はライブトラフィック​に対して参照しないでください。安定した名前であることが保証されていません。 dYYYYYの値を決定するには、deploy コマンドの出力を参照してください。

コンテンツ配信フローへのワイヤー接続 wiring

Edge関数のトラフィックは、web サイトのドメインに送信する必要があります。これは、通常、AEM Java スタックのカスタムドメインであり、はEdge Delivery Services Sitesのカスタムドメインである必要があります。

​1. 原点セレクターの定義 origin-selectors

Edge関数は、オリジンセレクタールールを介してCDN トラフィックをルーティングすることで呼び出されます。 cdn.yaml設定ファイルに次のファイルを追加します（または、存在しない場合は作成します）。

kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-weather-to-edge-function
        when: { reqProperty: path, equals: "/weather" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function
      - name: route-hello-world-to-edge-function
        when: { reqProperty: path, equals: "/hello-world" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function

オリジン選択ルールを使用すると、特定のパス、ドメイン、リクエストヘッダーなど、CDN ルールエンジンで利用可能なあらゆる条件に基づいて、トラフィックをエッジ関数にルーティングできます。 複数のルールで異なるパスを同じエッジ関数にルーティングできます。 完全なルール構文については、​ オリジンセレクターを参照してください。

​2. 設定のデプロイ deploy-to-cdn

Cloud Manager Git リポジトリにcdn.yamlをコミットし、コンフィギュレーション パイプラインをトリガーします。 パイプラインが正常に完了すると、エッジ関数エンドポイントは次の場所で使用できるようになります。

デバッグの場合は、ドメイン publish-pXXXXX-eYYYYY.adobeaemcloud.com （AEM Java スタック）またはpublish-pXXXXX-dYYYYY.adobeaemcloud.com （Edge Delivery Services サイト）のエッジ関数を参照できます。 安定した名前であることが保証されていないため、このドメインを実稼動用に使用しないでください。 dYYYYYの値を決定するには、deploy コマンドの出力を参照してください。

ローカル開発 local-development

ローカルで実行 local-run

http://127.0.0.1:7676でローカル開発サーバーを起動します。

aio aem edge-functions serve

ローカル ランタイムがサポートする内容について詳しくは、Compute JavaScript ドキュメント ​を参照してください。

テスト test-localdev

Mochaでテストスイートを実行します。

npm run test

リモートデバッグ remote-debugging

Adobe Managed CDNは、リモートデバッガーを公開しませんが、ログストリーミングを公開します。 デプロイされた関数のログをテールして、ターミナルでconsole.log出力を直接受信します。

aio aem edge-functions tail-logs <function-name>

キャッシュとキャッシュのパージ caching

Edge Functionsは、エッジにデータをキャッシュすることで、オリジンの読み込みを大幅に削減し、応答時間を短縮できます。 ただし、キャッシュには意図的な設計が必要です。特に、2つの独立したキャッシュレイヤー​が関与するEdge関数では、次のようになります。

Browser → AEM CDN (CDN Cache) → AEM Edge Functions (Fetch Cache) → Backend (AEM, APIs, etc.)

キャッシュを設定する前に、コンテンツの動作を考慮してください。

CDNとEdge関数の内部フェッチ キャッシュは独立して動作するため、基になるデータを変更するには、両方 レイヤーを意図的に無効化する必要があります。 このアーキテクチャを理解することは、信頼性の高いキャッシュ管理に不可欠です。

キャッシュ動作の設定、キャッシュの有効期間の制御、サロゲートキーの使用、キャッシュされたコンテンツのパージに関する詳細な技術的ガイダンスについては、AEM Edge Functionsでのキャッシュ ​を参照してください。

制限事項 limitations

呼び出しあたりの最大アウトバウンドフェッチ呼び出し max-fetch-calls

AEM Edge関数は、実行単位​で 32件のバックエンドリクエスト（つまり、関数が処理する受信リクエスト単位）のハードリミットを適用します。 この制限に達すると、以降のfetch()呼び出しは失敗し、次のエラーが発生します。

Requested backend named '…' does not exist

このエラーが表示され、オリジン設定が正しい場合、最も可能性の高い原因は、呼び出し単位のバックエンド要求クォータが使い果たされたことです。 プラットフォーム制限の完全なリストについては、Fastly Compute リソース制限を参照してください。

Edgeの高度な機能設定 advanced-function-configuration

オリジン origins

デフォルトでは、エッジ関数は任意のオリジンから取得できます。 関数を定義済みのオリジンのセットに制限するには、edgeFunctions.yamlのoriginsで宣言します。

origins:
  - name: my-origin-name
    domain: example.com

backend フェッチ オプションを使用して、関数コード内の名前付きオリジンを参照します。

const request = new Request("https://example.com/test");
const response = await fetch(request, { backend: "my-origin-name" });

Edge関数の設定変数 function-configuration

edgeFunctions.yamlのconfigs キーを使用して、環境変数を関数に公開します。 値は、config_defaultという名前の設定ストアに格納されます。

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: LOG_LEVEL
      value: DEBUG

関数コードで設定値を読み取ります。

import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore('config_default');
const logLevel = config.get('LOG_LEVEL') || 'info';

Edge関数の秘密変数 function-secrets

秘密鍵は参照され、保存されません。edgeFunctions.yaml value フィールドは、${{SECRET_REFERENCE}}構文を使用してCloud Manager シークレットを指している必要があります。 最初にCloud Managerで基になる秘密鍵を定義します。Cloud Manager秘密変数を参照してください。

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  secrets:
    - key: API_TOKEN
      value: ${{API_TOKEN_SECRET}}

ボイラープレートからSecretStoreManager ヘルパーを使用して、関数コードのシークレットを取得します。

import { SecretStoreManager } from "./lib/config";

const apiToken = await SecretStoreManager.getSecret('API_TOKEN');

Edgeファンクション KV ストア function-kv-store

Edge関数は、KV ストアを介して、実行時に任意のキー値データを読み取り、書き込むことができます。 有効にするには、edgeFunctions.yamlでkvs: trueを設定します。

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  kvs: true

これにより、kv_defaultという名前の空のKV ストアがプロビジョニングされます。 Fastly KV Store APIを使用して、エッジ関数コードから実行時に設定します。

import { KVStore } from "fastly:kv-store";

const kv = new KVStore('kv_default');

// Read a value
const entry = await kv.get('visit-count');
const count = entry ? Number(await entry.text()) : 0;

// Write a value
await kv.put('visit-count', String(count + 1));

ログ logging

AEM Edge Functionsは、AEM ログ転送機能と統合されています。 edgeFunctions.yamlと一緒にlogForwarding.yaml ファイルを作成します。

kind: "LogForwarding"
version: "1"
metadata:
  envTypes: ["rde", "dev", "stage", "prod"]
data:
  splunk:
    default:
      enabled: true
      host: "splunk-host.example.com"
      token: "${{SPLUNK_TOKEN}}"
      index: "AEMaaCS"

関数コードでロガーを使用して、構造化ログエントリを書きます。

import { Logger } from "fastly:logger";

const logger = new Logger("customerSplunk");
logger.log(JSON.stringify({
  method: event.request.method,
  url: event.request.url
}));