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

아티클
11/05/2024

적용 대상: 모든 API Management 계층

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

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

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

필수 조건

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

Important

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

포털에서 통화 추적

포털의 테스트 콘솔에서 API 요청을 추적하려면 다음 단계를 수행합니다. 이 예제에서는 이전 자습서에서 샘플 API를 가져온 것으로 가정합니다. 가져온 다른 API를 사용하여 유사한 단계를 수행할 수 있습니다.

Azure Portal에 로그인하고 API Management 인스턴스로 이동합니다.
API API>를 선택합니다.
API 목록에서 Petstore API를 선택합니다.
테스트 탭을 선택합니다.
ID로 애완 동물 찾기 작업을 선택합니다.
petId Query 매개 변수에 1을 입력합니다.
필요에 따라 "눈" 아이콘을 선택하여 요청에 사용된 Ocp-Apim-Subscription-Key 헤더의 값을 확인합니다.

팁

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

추적 정보 검토

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

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

API에 대한 추적 사용

사용할 curl때 API Management에 대한 요청, REST 클라이언트 확장이 있는 Visual Studio Code와 같은 REST 클라이언트 또는 클라이언트 앱에 대한 추적을 사용하도록 설정하려면 다음과 같은 높은 수준의 단계가 필요합니다. 현재 API Management REST API를 사용하여 다음 단계를 수행해야 합니다.

추적을 위한 토큰 자격 증명을 가져옵니다.
요청 헤더의 토큰 값을 Apim-Debug-Authorization API Management 게이트웨이에 추가합니다.
응답 헤더에서 추적 ID를 Apim-Trace-Id 가져옵니다.
추적 ID에 해당하는 추적을 검색합니다.

자세한 단계는 다음과 같습니다.

참고 항목

이러한 단계에는 API Management REST API 버전 2023-05-01-preview 이상이 필요합니다. REST API를 호출하려면 API Management 인스턴스에 기여자 이상의 역할을 할당받아야 합니다.
REST API 인증에 대한 자세한 내용은 Azure 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": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
    "purposes": ["tracing"]
}
```
토큰 자격 증명은 다음과 유사한 응답으로 반환됩니다.
```
{
      "token": "aid=api-name&......."
}
```
요청 헤더 에 토큰 값 추가 - API Management 게이트웨이에 대한 요청에 대한 추적을 사용하도록 설정하려면 헤더에 Apim-Debug-Authorization 토큰 값을 보냅니다. 예를 들어 이전 자습서에서 가져온 Petstore API에 대한 호출을 추적하려면 다음과 유사한 요청을 사용할 수 있습니다.
```
curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."
```
토큰에 따라 응답에는 다음 헤더 중 하나가 포함됩니다.
- 토큰이 유효한 경우 응답에는 다음과 유사한 값이 추적 ID인 헤더가 포함됩니다 Apim-Trace-Id .
```
Apim-Trace-Id: 0123456789abcdef....
```
- 토큰이 만료된 경우 응답에는 만료 날짜에 대한 정보가 포함된 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": "0123456789abcdef...."
}
```
응답 본문에는 게이트웨이에 대한 이전 API 요청에 대한 추적 데이터가 포함되어 있습니다. 추적은 포털의 테스트 콘솔에서 호출을 추적하여 볼 수 있는 추적과 유사합니다.

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

다음 단계

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

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

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

수정 버전 사용

다음을 통해 공유