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

# 修補程式庫來檢測下游呼叫
<a name="xray-sdk-python-patching"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。

若要檢測下游呼叫，請使用適用於 Python 的 X-Ray 開發套件來修補應用程式使用的程式庫。適用於 Python 的 X-Ray 開發套件可以修補下列程式庫。

**支援的程式庫**
+ `[botocore](https://pypi.python.org/pypi/botocore)`， `[boto3](https://pypi.python.org/pypi/boto3)` – 檢測 適用於 Python (Boto) 的 AWS SDK 用戶端。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Instrument PynamoDB 的 Amazon DynamoDB 用戶端版本。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、 `[aioboto3](https://pypi.python.org/pypi/aioboto3)` – 檢測適用於 Python 用戶端的 SDK [非同步](https://docs.python.org/3/library/asyncio.html)整合版本。
+ `[requests](https://pypi.python.org/pypi/requests)`， `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – 檢測高階 HTTP 用戶端。
+ `[httplib](https://docs.python.org/2/library/httplib.html)`、 [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – 檢測低階 HTTP 用戶端和使用它們的更高層級程式庫。
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` – 檢測 SQLite 用戶端。
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – 檢測 MySQL 用戶端。
+ `[pg8000](https://pypi.org/project/pg8000/)` – Instrument Pure-Python PostgreSQL 介面。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – Instrument PostgreSQL 資料庫轉接器。
+ `[pymongo](https://pypi.org/project/pymongo/)` – Instrument MongoDB 用戶端。
+ `[pymysql](https://pypi.org/project/PyMySQL/)` – 檢測 MySQL 和 MariaDB 的 PyMySQL 型用戶端。 MariaDB

當您使用修補的程式庫時，適用於 Python 的 X-Ray 開發套件會為呼叫建立子區段，並記錄來自請求和回應的資訊。區段必須透過軟體開發套件中介軟體或 AWS Lambda供軟體開發套件使用，以建立子區段。

**注意**  
若您使用 SQLAlchemy ORM，您可以透過匯入 SQLAlchemy 工作階段和查詢類別的軟體開發套件版本，來檢測您的 SQL 查詢。如需說明，請參閱[使用 SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm)。

若要修補所有可用程式庫，請使用 `aws_xray_sdk.core` 中的 `patch_all` 函數。有些程式庫 (例如 `httplib` 和 `urllib`) 可能需要呼叫 `patch_all(double_patch=True)` 以啟用雙重修補。

**Example main.py – 修補所有支援的程式庫**  

```
import boto3
import botocore
import requests
import sqlite3

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

patch_all()
```

若要修補單一程式庫，請以該程式庫名稱的元組來呼叫 `patch`。若要執行這個作業，您將需要提供單一個元素清單。

**Example main.py – 修補特定程式庫**  

```
import boto3
import botocore
import requests
import mysql-connector-python

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch

libraries = (['botocore'])
patch(libraries)
```

**注意**  
在某些情況下，您用來修補程式庫的鍵會與程式庫名稱不相符。有些鍵會做為一或多個程式庫的別名。  
`httplib`–`[httplib](https://docs.python.org/2/library/httplib.html)` 和 [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`

## 追蹤非同步工作的內容
<a name="xray-sdk-python-patching-async"></a>

對於`asyncio`整合式程式庫，或為[非同步函數建立子區段](xray-sdk-python-subsegments.md)，您還必須使用非同步內容設定適用於 Python 的 X-Ray 開發套件。匯入 `AsyncContext`類別，並將其執行個體傳遞至 X-Ray 記錄器。

**注意**  
Web 架構支援程式庫，例如 AIOHTTP，將不會經由 `aws_xray_sdk.core.patcher` 模組獲得處理。它們不會出現在支援程式庫的 `patcher` 目錄中。

**Example main.py – 修補程式 aioboto3**  

```
import asyncio
import aioboto3
import requests

from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch

libraries = (['aioboto3'])
patch(libraries)
```