# Lambda 메타데이터 엔드포인트 사용
<a name="configuration-metadata-endpoint"></a>

동일한 가용 영역 리소스(예: Amazon ElastiCache 및 Amazon RDS 엔드포인트)로 라우팅하여 지연 시간을 최적화하고 가용 영역을 인식하는 복원력 패턴을 구현할 수 있도록 Lambda 메타데이터 엔드포인트에서는 실행 중인 가용 영역(AZ)을 함수가 검색할 수 있습니다.

엔드포인트에서는 실행 환경 내 localhost HTTP API를 통해 간단한 JSON 형식으로 메타데이터를 반환하며 런타임과 확장 프로그램에 모두 액세스할 수 있습니다.

**Topics**
+ [시작하기](#metadata-endpoint-getting-started)
+ [가용 영역 ID 이해하기](#metadata-endpoint-az-ids)
+ [API 참조](#metadata-endpoint-api-reference)

## 시작하기
<a name="metadata-endpoint-getting-started"></a>

[Powertools for AWS Lambda](https://docs.aws.amazon.com/powertools/)에서는 Python, TypeScript, Java 및 .NET의 Lambda 메타데이터 엔드포인트 액세스용 유틸리티를 제공합니다. 유틸리티에서는 첫 번째 직접 호출 후 응답을 캐싱하고 SnapStart 캐시 무효화를 자동으로 처리합니다.

Powertools for AWS Lambda 메타데이터 유틸리티 사용 또는 메타데이터 엔드포인트 직접 호출

------
#### [ Python ]

Powertools 패키지 설치:

```
pip install "aws-lambda-powertools"
```

핸들러에서 메타데이터 유틸리티 사용:

**Example Powertools로 AZ ID 검색하기(Python)**  

```
from aws_lambda_powertools.utilities.lambda_metadata import get_lambda_metadata

def handler(event, context):
    metadata = get_lambda_metadata()
    az_id = metadata.availability_zone_id  # e.g., "use1-az1"

    return {"az_id": az_id}
```

------
#### [ TypeScript ]

Powertools 패키지 설치:

```
npm install @aws-lambda-powertools/commons
```

핸들러에서 메타데이터 유틸리티 사용:

**Example Powertools로 AZ ID 검색하기(TypeScript)**  

```
import { getMetadata } from '@aws-lambda-powertools/commons/utils/metadata';

const metadata = await getMetadata();

export const handler = async () => {
  const { AvailabilityZoneID: azId } = metadata;
  return azId;
};
```

------
#### [ Java ]

`pom.xml`에 Powertools 종속성 추가:

```
<dependencies>
    <dependency>
        <groupId>software.amazon.lambda</groupId>
        <artifactId>powertools-lambda-metadata</artifactId>
        <version>2.10.0</version>
    </dependency>
</dependencies>
```

핸들러에서 메타데이터 클라이언트 사용:

**Example Powertools로 AZ ID 검색하기(Java)**  

```
import software.amazon.lambda.powertools.metadata.LambdaMetadata;
import software.amazon.lambda.powertools.metadata.LambdaMetadataClient;

public class App implements RequestHandler<Object, String> {

    @Override
    public String handleRequest(Object input, Context context) {
        LambdaMetadata metadata = LambdaMetadataClient.get();
        String azId = metadata.getAvailabilityZoneId(); // e.g., "use1-az1"

        return "{\"azId\": \"" + azId + "\"}";
    }
}
```

------
#### [ .NET ]

Powertools 패키지 설치:

```
dotnet add package AWS.Lambda.Powertools.Metadata
```

핸들러에서 메타데이터 클래스 사용:

**Example Powertools로 AZ ID 검색하기(.NET)**  

```
using AWS.Lambda.Powertools.Metadata;

public class Function
{
    public string Handler(object input, ILambdaContext context)
    {
        var azId = LambdaMetadata.AvailabilityZoneId;
        return $"Running in AZ: {azId}";
    }
}
```

------
#### [ All Runtimes ]

모든 런타임에서는 메타데이터 엔드포인트를 지원합니다(사용자 지정 런타임 및 컨테이너 이미지 포함). 다음 예제를 사용하여 Lambda가 실행 환경에서 자동으로 설정하는 환경 변수를 사용하는 함수에서 메타데이터 API에 직접 액세스합니다.

**Example 메타데이터 엔드포인트에 직접 액세스하기**  

```
# Variables are automatically set by Lambda
METADATA_ENDPOINT="http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment"

# Make the request
RESPONSE=$(curl -s -H "Authorization: Bearer ${AWS_LAMBDA_METADATA_TOKEN}" "$METADATA_ENDPOINT")

# Parse the AZ ID
AZ_ID=$(echo "$RESPONSE" | jq -r '.AvailabilityZoneID')

echo "Function is running in AZ ID: $AZ_ID"
```

------

## 가용 영역 ID 이해하기
<a name="metadata-endpoint-az-ids"></a>

AZ ID(예: `use1-az1`)에서는 항상 모든 AWS 계정의 동일한 물리적 위치를 참조하는 반면에 AZ 이름(예: `us-east-1a`)은 특정 리전의 각 AWS 계정의 상이한 물리적 인프라에 매핑될 수 있습니다. 자세한 내용은 [크로스 계정 일관성을 위한 AZ ID](https://docs.aws.amazon.com/global-infrastructure/latest/regions/az-ids.html)를 참조하세요.

**AZ 이름으로 AZ ID 변환하기:**

AZ ID를 AZ 이름으로 변환하려면 EC2 [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html) API를 사용합니다. 이 API를 사용하려면 함수의 실행 역할에 `ec2:DescribeAvailabilityZones` 권한을 추가합니다.

## API 참조
<a name="metadata-endpoint-api-reference"></a>

### 환경 변수
<a name="metadata-endpoint-env-vars"></a>

Lambda에서는 모든 실행 환경에서 다음과 같은 환경 변수를 자동으로 설정합니다.
+ `AWS_LAMBDA_METADATA_API` - `{ipv4_address}:{port}` 형식의 메타데이터 서버 주소입니다(예: `169.254.100.1:9001`).
+ `AWS_LAMBDA_METADATA_TOKEN` - 현재 실행 환경의 고유 인증 토큰입니다. Lambda에서는 초기화 시 이 토큰을 자동으로 생성합니다. 모든 메타데이터 API 요청에 포함합니다.

### 엔드포인트
<a name="metadata-endpoint-url"></a>

`GET http://${AWS_LAMBDA_METADATA_API}/2026-01-15/metadata/execution-environment`

### 요청
<a name="metadata-endpoint-request"></a>

**필수 헤더:**
+ `Authorization` - 전달자 체계(`Bearer <token>`)가 있는 `AWS_LAMBDA_METADATA_TOKEN` 환경 변수의 토큰 값입니다. 이 토큰 기반 인증에서는 SSRF(서버 측 요청 위조) 취약성에 대한 심층 방어 보호를 제공합니다. 각 실행 환경에서는 초기화 시 무작위로 생성된 고유한 토큰을 수신합니다.

### 응답
<a name="metadata-endpoint-response"></a>

**Status:** `200 OK`

**Content-Type:** `application/json`

**Cache-Control:** `private, max-age=43200, immutable`

응답은 실행 환경 내에서 변경할 수 없습니다. 클라이언트에서는 응답을 캐싱하고 `Cache-Control` TTL을 준수해야 합니다. SnapStart 함수의 경우 실행 환경이 다른 AZ에 있을 수 있을 때 복원 후 클라이언트에서 메타데이터를 새로 고치도록 초기화 동안 TTL이 감소합니다. Powertools를 사용하는 경우 캐싱 및 SnapStart 무효화가 자동으로 처리됩니다.

**본문:**

```
{
  "AvailabilityZoneID": "use1-az1"
}
```

`AvailabilityZoneID` 필드에는 실행 환경이 실행 중인 가용 영역의 고유 식별자가 있습니다.

**참고**  
향후 업데이트에서 응답에 추가 필드를 추가할 수 있습니다. 클라이언트는 알 수 없는 필드를 무시하고 새 필드가 나타나면 실패하지 않아야 합니다.

### 오류 응답
<a name="metadata-endpoint-errors"></a>
+ **401 Unauthorized** - `Authorization` 헤더가 누락되었거나 유효하지 않은 토큰이 있습니다. `Bearer ${AWS_LAMBDA_METADATA_TOKEN}`을 전달 중인지 확인합니다.
+ **405 Method Not Allowed** - 요청 메서드가 `GET`이 아닙니다.
+ **500 Internal Server Error** - 서버 측 처리 오류입니다.