本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Lambda 中繼資料端點
<a name="configuration-metadata-endpoint"></a>

Lambda 中繼資料端點可讓您的函數探索他們在哪個可用區域 (AZ) 中執行，讓您能夠透過路由至 Amazon ElastiCache 和 Amazon RDS 端點等相同可用區域資源來最佳化延遲，並實作可用區域感知彈性模式。

端點會透過執行環境中的 localhost HTTP API 以簡單的 JSON 格式傳回中繼資料，並且可供執行時間和延伸存取。

**Topics**
+ [開始使用](#metadata-endpoint-getting-started)
+ [了解可用區域 IDs](#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 ]

將 Powertools 相依性新增至您的 `pom.xml`：

```
<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 執行期都支援中繼資料端點，包括自訂執行期和容器映像。使用以下範例，使用 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"
```

------

## 了解可用區域 IDs
<a name="metadata-endpoint-az-ids"></a>

AZ IDs （例如，`use1-az1`) 一律在所有 AWS 帳戶中參考相同的實體位置，而 AZ 名稱 （例如，`us-east-1a`) 可能會映射到特定區域中每個 AWS 帳戶中的不同實體基礎設施。如需詳細資訊，請參閱 [AZ IDs以取得跨帳戶一致性](https://docs.aws.amazon.com/global-infrastructure/latest/regions/az-ids.html)。

**將 AZ ID 轉換為 AZ 名稱：**

若要將 AZ ID 轉換為 AZ 名稱，請使用 Amazon 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 請求中。

### Endpoint
<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 結構描述之`AWS_LAMBDA_METADATA_TOKEN`環境變數的字符值：`Bearer <token>`。此字符型身分驗證可針對伺服器端請求偽造 (SSRF) 漏洞提供深度防禦。每個執行環境都會在初始化時收到唯一的隨機產生字符。

### 回應
<a name="metadata-endpoint-response"></a>

**狀態：** `200 OK`

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

**快取控制：** `private, max-age=43200, immutable`

回應在執行環境中是不可變的。用戶端應快取回應並遵循 `Cache-Control` TTL。對於 SnapStart 函數，TTL 會在初始化期間減少，因此當執行環境可能位於不同的可用區域中時，用戶端會在還原後重新整理中繼資料。如果您使用 Powertools，會自動處理快取和 SnapStart 無效。

**本文：**

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

`AvailabilityZoneID` 欄位包含執行環境執行所在可用區域的唯一識別符。

**注意**  
其他欄位可能會新增至未來更新的回應。用戶端應該忽略未知欄位，如果出現新欄位，則不會失敗。

### 錯誤回應
<a name="metadata-endpoint-errors"></a>
+ **401 未授權** – `Authorization`標頭遺失或包含無效的字符。驗證您正在傳遞 `Bearer ${AWS_LAMBDA_METADATA_TOKEN}`。
+ **405 不允許的方法** – 請求方法不是 `GET`。
+ **500 內部伺服器錯誤** – 伺服器端處理錯誤。