Edge 함수를 사용하여 API 엔드포인트 빌드

IMPORTANT
AEM Edge 함수는 현재 베타 버전입니다. 기능 및 설명서는 변경될 수 있습니다. 피드백을 받으려면 aemcs-edgecompute-feedback@adobe.com에 문의하십시오.

AEM Edge 함수는 Adobe CDN(Fastly Compute)에서 실행되는 JavaScript 모듈입니다. CDN 원본 선택기 규칙을 코드에서 가져오기 이벤트 처리기와 연결하여 하나 이상의 HTTP 끝점으로 노출합니다.

이 페이지에서는 계약서 및 주요 파일을 다룹니다. 처리기에서 다른 시스템에 대한 아웃바운드 fetch() 호출을 포함하여 모든 논리를 쓸 수 있습니다. Edge 런타임에 맞게 처리기를 빠르고 짧게 유지하십시오.

사전 요구 사항

  • 표준 템플릿을(를) 기반으로 하는 AEM Edge Functions 프로젝트
  • AEM Edge 기능 플러그인이 설치된 Adobe CLI

처음 설치하는 경우 AEM as a Cloud Service 설정 또는 Edge Delivery Services 설정을 참조하십시오.

HTTP 요청이 코드에 도달하는 방법

요청이 AEM Edge 함수에 2단계로 도달합니다. CDN 원본 선택기가 끝점을 함수로 라우팅한 다음 가져오기 이벤트 처리기가 실행됩니다.

Browser → CDN origin selector (cdn.yaml) → AEM Edge Function (index.js) → Your handler logic (optional fetch to other systems)
레이어
파일
책임
CDN
config/cdn.yaml
경로를 일치시키고 요청을 AEM Edge 함수에 전달합니다.
함수
config/edgeFunctions.yaml
AEM Edge 함수 이름과 선택적 configs, secrets 또는 kvs을(를) 선언합니다.
코드
src/index.js
끝점을 일치시키고 처리기 논리를 실행하고 Response을(를) 반환합니다.

원본 선택기와 함수 이름이 정렬되어야 합니다. edgeFunctions.yaml이(가) my-edge-function을(를) 선언하면 원본 선택기는 cdn.yaml에서 edgefunction-my-edge-function을(를) 사용합니다.

# config/edgeFunctions.yaml
kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function #<name-of-the-function>
# config/cdn.yaml (origin selector excerpt)
kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-status-endpoint-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/status" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: false # false to use the CDN cache for this path
      - name: route-my-api-to-edge-function # logical name for the origin selector rule
        when: { reqProperty: path, equals: "/my-api" } # path to match
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function # edgefunction-<name-of-the-function>
          skipCache: true # true to bypass the CDN cache for this path

각 끝점에는 cdn.yaml에 자체 원본 선택기 규칙이 필요합니다. 하나의 AEM Edge 함수는 여러 끝점을 제공할 수 있지만 CDN은 해당 함수에 대한 각 경로를 전달해야 합니다. 안정적인 응답을 위해 CDN 캐싱을 허용하려면 skipCache: false을(를) 설정하고, 동적 또는 개인화된 응답을 위해 CDN 캐시를 무시하려면 skipCache: true을(를) 설정하십시오.

원본 선택기 옵션에 대해서는 원본 선택기를 참조하십시오.

요청 처리

모든 AEM Edge 함수는 가져오기 이벤트 핸들러를 등록합니다. Adobe CDN은 일치하는 각 요청에 대해 해당 핸들러를 호출합니다. 처리기가 들어오는 Request을(를) 읽고 논리를 실행한 다음 Response을(를) 반환합니다.

// src/index.js
import { myApiHandler } from "./my-api.js";
import * as response from "./lib/response.js";

// entry point for the AEM Edge Function
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
  // event.request is a standard Fetch API Request (method, URL, headers, body)
  const req = event.request;
  const url = new URL(req.url);

  try {
    // endpoint matching
    if (url.pathname === "/status" && req.method === "GET") {
      return new Response("OK", { status: 200 });
    } else if (url.pathname === "/my-api" && req.method === "GET") {
      return await myApiHandler(req, event.client);
    }
    // add more endpoints here

    return response.notFound();
  } catch (err) {
    console.log(err);
    return response.error();
  }
}

주요 사항:

개념
세부 사항
진입점
addEventListener("fetch", ...) 가져오기 이벤트 처리기에 모든 요청을 연결합니다. FetchEvent.responseWith을(를) 참조하십시오.
요청
event.request은(는) 표준 Fetch API Request(메서드, URL, 헤더, 본문)입니다. 요청 참조 참조
응답
상태, 콘텐츠 형식 및 캐시 헤더를 제어하려면 new Response(body, { status, headers })을(를) 반환합니다. 응답 참조를 참조하십시오.
끝점 일치
handleRequest 내의 url.pathname, HTTP 메서드, 헤더 또는 쿼리 매개 변수에 대해 일치
클라이언트 메타데이터
event.client이(가) 클라이언트 IP 주소와 같은 연결 세부 정보를 표시합니다. FetchEvent.client를 참조하십시오.

index.js에서 일치하는 끝점이 있습니다. 끝점이 증가하면 위의 예에서 my-api.js이(가) 하는 것처럼 처리기 논리를 별도의 파일로 이동하여 가져옵니다. API 표면이 확장될 때 패턴에 대해서는 Edge 함수를 사용하여 여러 끝점 제공을 참조하십시오.

핸들러 논리 작성

각 엔드포인트 핸들러 내에서 Edge 런타임에 맞는 JavaScript을 실행할 수 있습니다. 일을 빨리 하고 단기간 동안 해라. 장기 실행 또는 대용량 컴퓨팅보다 간단한 변환, 지역 조회, 간단한 JSON 또는 HTML 응답 및 소규모 집계를 선호합니다.

최소 응답은 다음과 같습니다.

if (url.pathname === "/status" && req.method === "GET") {
  return new Response("OK", { status: 200 });
}

JSON, HTML 또는 일반 텍스트를 반환할 수 있습니다. 콘텐츠 형식 및 캐싱을 제어하려면 Response의 헤더를 설정하십시오.

return new Response(JSON.stringify({ status: "ok" }), {
  status: 200,
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "public, max-age=300",
  },
});

다른 시스템의 데이터가 필요하면 fetch()(으)로 호출하십시오. AEM Edge 기능에서 자격 증명을 유지합니다. 클라이언트 JavaScript의 비밀을 노출하지 마십시오.

// src/my-api.js
async function myApiHandler(req, client) {
  const backendRequest = new Request("https://api.example.com/data");

  // optionally, you can add headers to the request
  // backendRequest.headers.set("Authorization", `Bearer <your-access-token>`);

  const backendResponse = await fetch(backendRequest);

  if (!backendResponse.ok) {
    return new Response("Backend error", { status: 502 });
  }

  const data = await backendResponse.json();

  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "Cache-Control": "max-age=300",
    },
  });
}

export { myApiHandler };

아웃바운드 fetch() 호출은 일반적으로 다음 패턴을 따릅니다.

  1. 요청에서 컨텍스트를 파생합니다(headers, event.client, Fastly 지리적 위치 도우미).
  2. 다른 시스템에 Request을(를) 빌드합니다.
  3. await fetch(request)을(를) 호출합니다(선택적으로 이름이 backend인 원본 사용).
  4. 응답을 구문 분석하고 새 Response을(를) 클라이언트에 반환합니다.

플랫폼 제한이 적용됩니다. 각 호출은 최대 32개의 아웃바운드 가져오기 호출​을 지원합니다. 가져오기 호출에 대한 캐시 동작은 AEM Edge 함수에서 캐싱을 참조하십시오.

추가 코드 예

전체 작업 예제는 AEM Edge 함수 빌러플레이트를 참조하십시오.

파일
표시 내용
간단한 응답
src/index.js
경로 일치 및 핸들러에 빌드된 응답
외부 API
src/weather.js
지역 조회 및 아웃바운드 fetch()

추가 리소스

recommendation-more-help
experience-manager-learn-help-cloud-service