자습서: 요청 추적을 사용하여 API 디버그

아티클
06/25/2024

적용 대상: 사용량 | 개발자 | 기본 | 표준 | 프리미엄

이 자습서에서는 Azure API Management에서 요청 처리를 조사(추적)하는 방법을 설명합니다. 추적은 API를 디버그하고 문제를 해결하는 데 도움을 줍니다.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

테스트 콘솔에서 호출 예 추적
요청 처리 단계 검토
API에 대한 추적 사용

참고 항목

현재 API 요청 추적은 Basic v2 및 Standard v2 계층에서 지원되지 않습니다.

필수 조건

Azure API Management 용어를 익힙니다.
다음 빠른 시작 Azure API Management 인스턴스 만들기를 완료합니다.
또한, 다음 자습서 첫 번째 API 가져오기 및 게시를 완료합니다.

Important

요청에 Ocp-Apim-Trace 헤더를 사용하고 Ocp-Apim-Trace-Location 응답 헤더 값을 사용하는 API Management 요청 추적은 더 이상 사용되지 않습니다.
보안을 강화하기 위해 이제 API Management REST API를 사용하여 시간 제한 토큰을 가져오고 요청의 토큰을 게이트웨이에 전달하여 개별 API 수준에서 추적을 사용하도록 설정할 수 있습니다. 자세한 내용은 API 추적 사용을 참조하세요.
추적을 사용하도록 설정하면 추적 데이터의 중요한 정보가 노출될 수 있으므로 주의해야 합니다. 추적 데이터를 보호하기 위해 적절한 보안 조치가 마련되어 있는지 확인합니다.

포털에서 통화 추적

Azure Portal에 로그인하고 API Management 인스턴스로 이동합니다.
API를 선택합니다.
API 목록에서 Demo Conference API를 선택합니다.
테스트 탭을 선택합니다.
GetSpeakers 작업을 선택합니다.
필요에 따라 "눈" 아이콘을 선택하여 요청에 사용된 Ocp-Apim-Subscription-Key 헤더의 값을 확인합니다.

팁

포털에서 다른 구독에 대한 키를 검색하여 Ocp-Apim-Subscription-Key 값을 재정의할 수 있습니다. 구독을 선택하고 다른 구독에 대한 바로 가기 메뉴(...)를 엽니다. 키 표시/숨기기를 선택하고 키 중 하나를 복사합니다. 필요한 경우 키를 다시 생성할 수도 있습니다. 그런 다음, 테스트 콘솔에서 + 헤더 추가를 선택하여 새 키 값이 있는 Ocp-Apim-Subscription-Key 헤더를 추가합니다.
추적을 선택합니다.

추적 정보 검토

호출이 완료되면 HTTP 응답의 추적 탭으로 이동합니다.
다음 링크 중 하나를 선택하여 자세한 추적 정보로 이동합니다. 인바운드, 백 엔드, 아웃바운드, 오류 발생 시.
- 인바운드 - 호출자로부터 받은 원래 요청 API Management 및 요청에 적용된 정책을 보여줍니다. 예를 들어 자습서: API 변환 및 보호에 정책을 추가한 경우 여기에 표시됩니다.
- 백 엔드 - API Management가 API 백 엔드로 보낸 요청과 수신된 응답을 보여줍니다.
- 아웃바운드 - 호출자에게 다시 보내기 전에 응답에 적용되는 정책을 보여줍니다.
- 오류 발생 시 - 요청을 처리하는 동안 발생한 오류와 오류에 적용된 정책을 표시합니다.
팁

각 단계는 API Management에서 요청이 수신된 이후에 경과된 시간도 표시합니다.

API에 대한 추적 사용

curl, REST 클라이언트 확장이 포함된 Visual Studio Code와 같은 REST 클라이언트 또는 클라이언트 앱을 사용하여 API Management에 요청할 때 API 추적을 사용하도록 설정할 수 있습니다.

API Management REST API에 대한 호출을 사용하여 다음 단계에 따라 추적을 사용하도록 설정합니다.

참고 항목

다음 단계에는 API Management REST API 버전 2023-05-01-preview 이상이 필요합니다. REST API를 호출하려면 API Management 인스턴스에 기여자 이상의 역할을 할당받아야 합니다.

디버그 자격 증명 나열 API를 호출하여 추적 자격 증명을 가져옵니다. URI에 게이트웨이 ID를 전달하거나 클라우드에서 인스턴스의 관리 게이트웨이에 "관리"을 사용합니다. 예를 들어, 관리 게이트웨이에 대한 추적 자격 증명을 가져오려면 다음과 유사한 호출을 사용합니다.
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
요청 본문에서 추적하려는 API의 전체 리소스 ID를 전달하고 purposes를 tracing으로 지정합니다. 기본적으로 응답으로 반환된 토큰 자격 증명은 1시간 후에 만료되지만 페이로드에 다른 값을 지정할 수 있습니다.
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes": ["tracing"]
}
```
토큰 자격 증명은 다음과 유사한 응답으로 반환됩니다.
```
{
      "token": "aid=api-name&p=tracing&ex=......."
}
```
API Management 게이트웨이에 대한 요청 추적을 사용하도록 설정하려면 Apim-Debug-Authorization 헤더에 토큰 값을 보냅니다. 예를 들어, 데모 컨퍼런스 API에 대한 호출을 추적하려면 다음과 유사한 호출을 사용합니다.
```
curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
```
토큰에 따라 응답에는 다양한 헤더가 포함됩니다.
- 토큰이 유효한 경우 응답에는 값이 추적 ID인 Apim-Trace-Id 헤더가 포함됩니다.
- 토큰이 만료된 경우 응답에는 만료 날짜에 대한 정보가 포함된 Apim-Debug-Authorization-Expired 헤더가 포함됩니다.
- 잘못된 API에 대해 토큰을 가져오는 경우 응답에는 오류 메시지와 함께 Apim-Debug-Authorization-WrongAPI 헤더가 포함됩니다.
추적을 검색하려면 이전 단계에서 가져오는 추적 ID를 게이트웨이의 추적 나열 API에 전달합니다. 예를 들어, 관리 게이트웨이에 대한 추적을 검색하려면 다음과 유사한 호출을 사용합니다.
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
요청 본문에 이전 단계에서 가져오는 추적 ID를 전달합니다.
```
{
    "traceId": "<trace ID>"
}
```
응답 본문에는 게이트웨이에 대한 이전 API 요청에 대한 추적 데이터가 포함되어 있습니다. 추적은 포털의 테스트 콘솔에서 호출을 추적하여 볼 수 있는 추적과 유사합니다.

추적 정보를 사용자 지정하는 방법에 대한 자세한 내용은 추적 정책을 참조하세요.

다음 단계

이 자습서에서는 다음 작업 방법을 알아보았습니다.

예제 호출 추적
요청 처리 단계 검토
API에 대한 추적 사용

다음 자습서를 진행합니다.

수정 버전 사용

다음을 통해 공유