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

# 透過 HTTP 端點記錄擷取
<a name="CWL_HTTP_Endpoints"></a>

Amazon CloudWatch Logs 提供 HTTP 端點，可讓您使用簡單的 HTTP POST 請求將日誌直接傳送至 CloudWatch Logs。這些端點同時支援 SigV4 和承載字符身分驗證。

**重要**  
我們建議對可以整合 AWS SDK 的所有生產工作負載使用 SigV4 身分驗證。SigV4 使用短期登入資料，並提供最強大的安全狀態。承載字符 (API 金鑰） 身分驗證適用於 SigV4 不可行的情況，例如不支援 AWS SDK 整合的第三方日誌轉送器。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[長期存取金鑰的替代方案](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)。

CloudWatch Logs 支援下列 HTTP 擷取端點：


| Endpoint | 路徑 | 內容類型 | 格式 | 
| --- | --- | --- | --- | 
| [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json 或 application/x-protobuf | OTLP JSON 或 Protobuf | 
| [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | HLC 格式 | 
| [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json 或 application/x-ndjson | 換行分隔的 JSON | 
| [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | JSON 物件或陣列 | 

## 常見行為
<a name="CWL_HTTP_Endpoints_Common"></a>

所有 HTTP 擷取端點都共用下列行為：

**身分驗證**

所有端點都支援 SigV4 和承載字符身分驗證：
+ **SigV4 （建議）** – 標準 AWS 簽章第 4 版簽署。每當您的應用程式或基礎設施支援 AWS SDK 或 可以簽署請求時，請使用 SigV4。SigV4 使用短期憑證，是最安全的身分驗證方法。
+ **承載字符** – 使用 `Authorization: Bearer <ACWL token>`標頭。
  + 權杖必須是有效的 ACWL 承載權杖。如需設定說明，請參閱 [設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)。
  + 需要 `logs:PutLogEvents`和 `logs:CallWithBearerToken` IAM 許可。

**日誌群組和日誌串流**
+ 透過標頭提供： `x-aws-log-group`和 `x-aws-log-stream`
+ 除了 `?logGroup=<name>&logStream=<name>` OTLP 之外，所有端點也支援查詢參數。
+ 您無法對相同的參數同時使用查詢參數和標頭。
+ 日誌群組和日誌串流都是必要的。

**回應**
+ 成功：`HTTP 200`使用內文 `{}`
+ 驗證錯誤： `HTTP 400`
+ 驗證失敗： `HTTP 401`

## HTTP 擷取端點的比較
<a name="CWL_HTTP_Endpoints_Comparison"></a>


| 功能 | HLC 日誌 | ND-JSON 日誌 | 結構化 JSON 日誌 | OpenTelemetry 日誌 | 
| --- | --- | --- | --- | --- | 
| 路徑 | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs | 
| 內容類型 | application/json | application/json 或 application/x-ndjson | application/json | application/json 或 application/x-protobuf | 
| 時間戳記欄位 | "time" （秒） | "timestamp" （毫秒） | "timestamp" （毫秒） | "timeUnixNano" （奈秒） | 
| 必要欄位 | "event" | 無 | 無 | OTLP 結構 ("resourceLogs") | 
| 部分成功回應 | 否 | 是 | 是 | 是 | 
| 查詢參數支援 | 是 | 是 | 是 | 否 （僅限標頭） | 
| 實體中繼資料 | 是 | 是 | 是 | 否 | 
| 接受基本概念 | 否 | 是 | 否 | 否 | 
| 行型剖析 | 否 | 是 | 否 | 否 | 
| Protobuf 支援 | 否 | 否 | 否 | 是 | 
| Retry-After 標頭 | 否 | 否 | 否 | 是 | 

## 選擇端點
<a name="CWL_HTTP_Endpoints_Choosing"></a>
+ **使用 HLC 格式？** 使用 HLC 日誌。您現有的 HLC 承載會以最少的變更運作。
+ **line-by-line串流日誌？** 使用 ND-JSON 日誌。最適合每行發出一個事件的日誌管道。最靈活 – 接受任何 JSON 值類型。
+ **傳送結構化 JSON 承載？** 使用結構化 JSON 日誌。最適合產生格式正確的 JSON 物件或陣列的應用程式。
+ **已使用 OpenTelemetry？** 使用 OpenTelemetry Logs。接受 OTLP JSON 或 Protobuf 格式，並支援部分成功回應與重試語意。