AEM Edge 함수 aem-edge-functions

AEM Edge Functions를 사용하면 CDN 계층에서 JavaScript을 실행하여 데이터 처리를 최종 사용자에게 가깝게 할 수 있습니다. 이를 통해 지연 시간을 줄이고 원본을 왕복하지 않고도 응답형의 동적 경험을 사용할 수 있습니다.

일반적인 사용 사례는 다음과 같습니다.

AEM Edge 기능은 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 기능 플러그인 설치:

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

사용자 환경에 대한 플러그인 인증 및 구성:

aio login
aio aem edge-functions setup

setup 명령은 로그인한 다음 AEM Edge 기능을 사용할 AEM 환경을 선택하라는 메시지를 표시합니다.

보일러판 복제 boilerplate

aem-edge-functions-boilerplate을(를) 고유한 저장소에 복사한 다음 종속성을 설치하십시오.

npm install

AEM Edge 기능 등록 register-your-function

AEM Edge 함수는 YAML 구성 파일에서 선언되고 Cloud Manager 구성 파이프라인을 통해 배포됩니다.

​1. 구성 파이프라인 설정 configuration-pipeline

Edge 함수를 생성하기 전에 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을 사용하여 Edge 함수가 CDN에 등록되도록 파이프라인을 배포합니다.

AEM Edge 기능 코드 작성, 빌드 및 배포 build-deploy

작성자 author

보일러판의 src 폴더를 시작점으로 사용하여 Edge 함수 코드 비즈니스 논리를 작성하십시오.

빌드 build

배포를 위해 Edge 함수 코드를 패키징합니다.

aio aem edge-functions build

배포 deploy

패키지된 edge 함수 코드를 명명된 edge 함수에 배포합니다. function-name 인수는 edgeFunctions.yaml의 name 값과 일치해야 합니다.

aio aem edge-functions deploy <function-name>

테스트 test

Edge 함수가 예상대로 작동하는지 확인합니다. 다음에서 테스트할 수 있습니다.

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 접두사가 있는 이 도메인은 디버깅용으로만 사용되지만 은(는) 안정적인 이름이 될 수 없으므로 실시간 트래픽에 참조되지 않아야 합니다. dYYYY의 값을 확인하려면 deploy 명령의 출력을 참조하십시오.

컨텐츠 전달 흐름에 연결 wiring

Edge 함수 트래픽은 웹 사이트의 도메인으로 전송되어야 합니다. 이 도메인은 일반적으로 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 규칙 엔진에서 사용할 수 있는 조건을 기반으로 트래픽을 Edge 함수에 라우팅할 수 있습니다. 여러 규칙을 사용하면 서로 다른 경로를 동일한 에지 함수로 라우팅할 수 있습니다. 전체 규칙 구문은 원본 선택기를 참조하십시오.

​2. 구성 배포 deploy-to-cdn

Cloud Manager Git 저장소에 cdn.yaml을(를) 커밋하고 구성 파이프라인을 트리거합니다. 파이프라인이 정상적으로 완료되면 Edge 함수 엔드포인트를 사용할 수 있는 위치:

디버깅을 위해 도메인 publish-pXXXXX-eYYYYY.adobeaemcloud.com(AEM Java 스택의 경우) 또는 publish-pXXXXX-dYYYYY.adobeaemcloud.com(Edge Delivery Services 사이트의 경우)에서 Edge 함수를 참조할 수 있습니다. 이 도메인은 안정적인 이름이 아니므로 프로덕션 사용에 사용하지 마십시오. dYYYY의 값을 확인하려면 deploy 명령의 출력을 참조하십시오.

로컬 개발 local-development

로컬에서 실행 local-run

http://127.0.0.1:7676에서 로컬 개발 서버 시작:

aio aem edge-functions serve

로컬 런타임에서 지원하는 기능에 대한 자세한 내용은 이 JavaScript 계산 설명서를 참조하세요.

테스트 test-localdev

Mocha​(으)로 테스트 도구 모음 실행:

npm run test

원격 디버깅 remote-debugging

Adobe Managed CDN은 원격 디버거를 노출하지 않지만 로그 스트리밍을 노출합니다. 배포된 함수에 대한 로그를 추적하여 터미널에서 직접 console.log 출력을 받습니다.

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

캐싱 및 캐시 삭제 caching

Edge 함수는 에지에서 데이터를 캐싱하여 원본 로드를 크게 줄이고 응답 시간을 향상시킬 수 있습니다. 그러나 캐싱은 의도적인 설계가 필요합니다. 특히 두 개의 독립적인 캐시 레이어​가 포함된 Edge 함수에서:

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

캐싱을 구성하기 전에 콘텐츠의 동작 방식을 고려하십시오.

CDN과 Edge 함수의 내부 가져오기 캐시는 독립적으로 작동하므로 기본 데이터를 변경하려면 둘 다 레이어를 의도적으로 무효화해야 합니다. 안정적인 캐시 관리를 위해서는 이 아키텍처를 이해하는 것이 필수적입니다.

캐싱 동작 구성, 캐시 수명 제어, 대리 키 사용 및 캐시된 콘텐츠 제거에 대한 자세한 기술 지침은 AEM Edge 함수에서 캐싱을 참조하십시오.

제한 사항 limitations

호출당 최대 아웃바운드 가져오기 호출 수 max-fetch-calls

AEM Edge 함수는 실행당 32개의 백엔드 요청(즉, 함수에 의해 처리된 수신 요청당)에 대해 엄격한 제한을 적용합니다. 이 한도에 도달하면 fetch()개의 추가 호출이 실패하고 다음 오류가 발생합니다.

Requested backend named '…' does not exist

이 오류가 표시되고 원본 구성이 올바른 경우 호출당 백엔드 요청 할당량이 소진되었을 가능성이 높습니다. 플랫폼 제한의 전체 목록은 빠른 계산 리소스 제한을 참조하십시오.

고급 Edge 기능 구성 advanced-function-configuration

원본 origins

기본적으로 Edge 함수는 모든 원본에서 가져올 수 있습니다. 함수를 정의된 원본 집합으로 제한하려면 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 Function KV Store 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 스토어 API를 사용하여 Edge 함수 코드에서 런타임에 채웁니다.

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 함수는 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
}));