Lambda メタデータエンドポイントの使用 - AWS Lambda

Lambda メタデータエンドポイントの使用

Lambda メタデータエンドポイントを使用すると、関数は実行中のアベイラビリティーゾーン (AZ) を検出できるため、Amazon ElastiCache や Amazon RDS エンドポイントなどの同じ AZ リソースにルーティングしてレイテンシーを最適化し、AZ 対応のレジリエンスパターンを実装できます。

エンドポイントは、実行環境内の localhost HTTP API を介してシンプルな JSON 形式でメタデータを返し、ランタイムと拡張機能の両方からアクセス可能です。

開始方法

Powertools for AWS Lambda は、Python、TypeScript、Java、および .NET で Lambda メタデータエンドポイントにアクセスするためのユーティリティを提供します。ユーティリティは、最初の呼び出し後にレスポンスをキャッシュし、SnapStart キャッシュの無効化を自動的に処理します。

Powertools for AWS Lambda メタデータユーティリティを使用するか、メタデータエンドポイントを直接呼び出す

Python

Powertools パッケージをインストールする:

pip install "aws-lambda-powertools"

ハンドラーでメタデータユーティリティを使用する:

例 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

ハンドラーでメタデータユーティリティを使用する:

例 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

Powertools の依存関係を pom.xml に追加する:

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

ハンドラーでメタデータクライアントを使用する:

例 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

ハンドラーでメタデータクラスを使用する:

例 Powertools (.NET) を使用した AZ ID の取得
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 ランタイムは、カスタムランタイムやコンテナイメージを含むメタデータエンドポイントをサポートします。Lambda が実行環境で自動的に設定する環境変数を使用して、関数から直接メタデータ API にアクセスするには、次の例を使用してください。

例メタデータエンドポイントへの直接アクセス
# 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

AZ ID (use1-az1 など) は常にすべての AWS アカウントで同じ物理的な場所を参照しますが、AZ 名 (us-east-1a など) は特定のリージョンの各 AWS アカウントの異なる物理インフラストラクチャにマッピングされる場合があります。詳細については、「クロスアカウントの一貫性を確保するための AZ ID」を参照してください。

AZ ID を AZ 名に変換する:

AZ ID を AZ 名に変換するには、Amazon EC2 DescribeAvailabilityZones API を使用します。この API を使用するには、関数の実行ロールに ec2:DescribeAvailabilityZones アクセス許可を追加します。

API リファレンス

環境変数

Lambda はすべての実行環境で次の環境変数を自動的に設定する:

  • AWS_LAMBDA_METADATA_API{ipv4_address}:{port} 形式のメタデータサーバーアドレス (例: 169.254.100.1:9001)。

  • AWS_LAMBDA_METADATA_TOKEN – 現在の実行環境の一意の認証トークン。Lambda は、初期化時にこのトークンを自動的に生成します。すべてのメタデータ API リクエストに含めます。

Endpoint

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

リクエスト

必要なヘッダー:

  • Authorization – ベアラースキームの AWS_LAMBDA_METADATA_TOKEN 環境変数のトークン値: Bearer <token>。このトークンベースの認証は、サーバー側のリクエスト偽造 (SSRF) の脆弱性に対する多層防御を提供します。各実行環境は、初期化時にランダムに生成された一意のトークンを受け取ります。

応答

Status: 200 OK

Content-Type: application/json

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

レスポンスは実行環境内で変更できません。クライアントはレスポンスをキャッシュし、Cache-Control TTL を尊重する必要があります。SnapStart 関数の場合、TTL は初期化中に減少するため、実行環境が別の AZ にある可能性がある場合に、クライアントは復元後にメタデータを更新します。Powertools を使用する場合、キャッシュと SnapStart の無効化は自動的に処理されます。

本文:

{ "AvailabilityZoneID": "use1-az1" }

AvailabilityZoneID フィールドには、実行環境が実行されているアベイラビリティーゾーンの一意の識別子が含まれます。

注記

今後の更新でレスポンスに追加のフィールドが追加される場合があります。クライアントは不明なフィールドを無視し、新しいフィールドが表示されても失敗しないようにする必要があります。

エラーレスポンス

  • 401 UnauthorizedAuthorization ヘッダーがないか、無効なトークンが含まれています。Bearer ${AWS_LAMBDA_METADATA_TOKEN} を渡すことを確認します。

  • 405 メソッドは許可されていません – リクエストメソッドは GET ではありません。

  • 500 内部サーバーエラー – サーバー側の処理エラー。