Apidog에서 전역 파라미터 설정 방법 (모든 요청에 인증 헤더 자동 전송)

프로젝트에 40개의 엔드포인트가 있고, 모든 엔드포인트는 모든 호출에서 동일한 Authorization: Bearer ... 헤더와 X-Api-Version 헤더를 필요로 합니다. 각 요청에 이 두 줄을 수동으로 추가하는 것은 느리고, 더 나쁜 것은 일관성이 없어진다는 것입니다. 한 엔드포인트는 토큰을 받지만 다른 엔드포인트는 잊어버리고, 결국 40개 경로 중 3개에서만 발생하는 401 오류를 추적하느라 오후를 허비하게 됩니다.

더 나은 방법이 있습니다. Apidog를 사용하면 매개변수를 한 번 정의하고 모든 요청에 자동으로 적용할 수 있습니다. 프로젝트 수준에서 헤더를 설정하고, 토큰을 변수로 참조하면, 단일 요청도 건드리지 않고 모든 엔드포인트가 이를 상속합니다. 이 가이드는 이를 위한 세 가지 문서화된 지렛대(전역 매개변수, 환경 변수, 폴더 범위 스크립트 대체)를 안내합니다. 이 가이드를 마치면 인증 헤더와 버전 헤더를 모든 항목에 첨부하는 작동하는 설정을 갖게 되며, 헤더가 실제로 전송되었는지 증명할 수 있는 방법도 알게 됩니다. 변수에 대한 더 깊은 배경 지식을 먼저 알고 싶다면, Apidog에서 변수 마스터하기에 대한 저희 가이드가 이 가이드와 잘 어울립니다.

button

모든 호출에 표준 헤더를 포함하는 요청의 개념은 Apidog에만 있는 것이 아닙니다. 이는 MDN HTTP 헤더 참조에서 설명하는 것과 동일한 패턴입니다: 각 요청과 함께 전달되는 작은 키/값 쌍 집합입니다. Apidog의 역할은 그 집합을 한 번만 설정할 수 있도록 하는 것입니다.

“전역 매개변수”가 실제로 의미하는 것

Apidog의 전역 매개변수는 단일 엔드포인트가 아닌 전체 프로젝트에 적용되는 요청 매개변수입니다. 이를 한 번 정의하면 Apidog가 일치하는 요청에 자동으로 첨부합니다.

전역 매개변수는 네 가지 위치를 다루며, 이것이 전체 기능의 핵심입니다:

헤더 (요청 헤더) - Authorization 또는 X-Api-Version과 같은 항목을 위한 것.
쿠키 (쿠키 정보) - 세션 쿠키를 위한 것.
쿼리 (URL 쿼리 매개변수) - 모든 URL에 추가되는 ?api_key=와 같은 값을 위한 것.
바디 (요청 바디 매개변수) - 모든 요청 본문이 포함해야 하는 필드를 위한 것.

인증 헤더 사용 사례의 경우 헤더를 원합니다. 표준 값이 쿠키, 쿼리 문자열 또는 본문 필드에 있는 경우 나머지 세 가지도 동일하게 작동합니다.

시작하기 전에 중요한 규칙이 하나 있습니다: 전역 매개변수는 엔드포인트 수준에서 정의된 매개변수보다 우선순위가 낮습니다. 특정 요청이 이미 자체 Authorization 헤더를 설정한 경우, 해당 엔드포인트 수준 값이 우선하고 전역 값은 무시됩니다. 전역 매개변수는 엔드포인트가 자체적으로 지정하지 않았을 때 채워지는 기본값으로 생각해야 하며, 모든 것을 덮어쓰는 강력한 재정의가 아닙니다. 이러한 우선순위 덕분에 대규모 프로젝트에서 전역 매개변수를 안전하게 사용할 수 있습니다.

모든 요청에 전역 헤더 설정하기

여기 핵심 안내가 있습니다. 목표: 프로젝트의 모든 엔드포인트에 Authorization 및 X-Api-Version을 편집 없이 첨부합니다.

단계 1: 환경 관리 열기

전역 매개변수는 페이지 오른쪽 상단에서 열 수 있는 환경 관리에 있습니다. 이곳은 프로젝트 전반에 적용되는 매개변수의 진입점이며, Apidog 문서에서는 모든 요청과 함께 전달되는 값의 본거지라고 설명합니다. 이를 열면 위치별로 매개변수를 추가하는 섹션이 보일 것입니다.

단계 2: 헤더 위치 선택

인증 헤더를 추가하는 것이므로 헤더(요청 헤더 위치)를 선택합니다. 표준 값이 쿠키, 쿼리 매개변수 또는 본문 필드인 경우 대신 쿠키, 쿼리 또는 본문을 선택했을 것입니다. 네 가지 모두 작동 방식은 동일합니다.

단계 3: 매개변수 세부 정보 입력

각 전역 매개변수는 고정된 속성 집합을 가지고 있습니다. 첫 번째 헤더에 대해 다음을 입력하세요:

이름: Authorization
유형: 매개변수 유형 (헤더 값의 경우 문자열).
기본값: Bearer {{token}} (아래에서 {{token}} 부분에 대해 더 자세히 설명합니다).
설명: "모든 인증된 엔드포인트에 대한 베어러 토큰."과 같은 짧은 메모.

필수 매개변수에는 기본값 필드와 필수 표시(별표 *)도 나타납니다. 동일한 방식으로 버전 헤더에 대해 두 번째 행을 추가하세요:

이름: X-Api-Version
유형: 문자열
기본값: 2024-08-01
설명: "모든 요청에 고정된 API 버전."

단계 4: 매개변수 활성화

각 매개변수에는 오른쪽에 활성화/비활성화 스위치가 있습니다. 이를 켜서 매개변수를 활성화하십시오. 이 토글은 나중에 유용합니다: 디버깅 세션을 위해 전역 헤더를 잠시 비활성화해야 할 경우, 이를 삭제하고 전체를 다시 입력하는 대신 여기서 비활성화할 수 있습니다.

단계 5: 저장

설정을 저장합니다. 이제 두 헤더 모두 전역입니다. 특정 엔드포인트가 이 중 하나를 재정의하지 않는 한, 프로젝트의 모든 요청은 Authorization과 X-Api-Version을 포함하게 됩니다.

단계 6: 실제로 전송되었는지 증명

작동했다고 믿지 말고 확인하세요. 프로젝트에서 아무 요청이나 보낸 다음 응답 콘솔에서 실제 요청(Actual Request) 탭을 엽니다. 이 탭은 변수가 실제 값으로 대체된 채로 요청이 전송된 방식을 정확하게 보여줍니다. 여기에 두 헤더가 모두 나열되어 있어야 합니다:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

헤더가 실제 요청에 나타나면, 실제로 전송된 것입니다. 이는 전체 설정에서 가장 유용한 부분인데, "적용된 것 같아"를 "적용된 것을 확인할 수 있어"로 바꿔주기 때문입니다.

헤더에서 비밀을 숨기세요: 변수를 사용하세요

위의 기본값이 Bearer {{token}}이었고, Bearer sk_live_7f3a9c2e1b8d4056가 아니었음을 주목하세요. 이 이중 중괄호 구문은 원시 토큰을 매개변수에 하드코딩하는 대신 변수를 참조합니다. Bearer 스키마 자체는 RFC 6750에 정의되어 있으며, MDN Authorization 헤더 참조는 서버가 이를 읽는 방법을 다룹니다. Apidog 문서는 보안 측면에 대해 명확히 언급합니다: 인증 토큰 및 API 키와 같은 민감한 데이터의 경우, 원시 값을 일반 텍스트 기본값으로 저장하는 대신 환경 변수를 사용하십시오. 변수는 여러 요청 및 스크립트에서 사용하는 값에 대한 동적 자리 표시자이며, 매개변수 정의에서 비밀을 제거합니다.

다음은 token 변수를 설정하는 방법입니다:

오른쪽 상단의 환경 아이콘(≡ 아이콘)을 클릭합니다. 이곳은 환경 관리와는 다른 진입점이라는 점에 유의하세요. ≡ 아이콘은 변수가 있는 곳입니다.
전역 변수 섹션을 찾습니다.
예를 들어, 베어러 시크릿 값으로 token 변수를 생성합니다.
저장을 클릭합니다.

이제 전역 헤더 값 Bearer {{token}}은 전송 시 Bearer <실제 비밀>으로 해석되며, 실제 요청 탭에서 대체가 확인됩니다. 변수 이름 위에 마우스를 올리면 어디에서든 현재 값과 범위를 표시하여 올바른 변수를 참조했는지 빠르게 확인할 수 있습니다.

이러한 조합은 권장되는 패턴입니다: 전역 매개변수가 헤더 슬롯을 소유하고, 변수가 비밀을 소유합니다. API 클라이언트 환경 및 비밀 관리에 대한 심층 분석에서는 공유하거나 커밋할 수 있는 어떤 것에서도 토큰을 제외하는 방법에 대해 더 자세히 설명합니다.

환경별로 값 전환

변수는 여러 개 있을 때 더 유용해집니다. 실제 프로젝트는 개발, 테스트 및 프로덕션용으로 다른 서버에 접근하며, 각 서버는 일반적으로 다른 토큰을 원합니다. 각 세트를 자체 환경 아래에 그룹화한 다음, ≡ 아이콘 옆의 환경 드롭다운을 사용하여 환경을 전환합니다(샘플 환경은 Local Mock으로 명명될 수 있습니다). 환경을 전환하면 요청이 다른 서버 세트를 가리키고 해당 환경의 변수 값으로 바뀝니다. 전역 Bearer {{token}} 헤더는 동일하게 유지되며, 환경에 따라 해결된 비밀만 변경됩니다. 이 위에 인증 흐름을 구축하는 경우, 보안 체계 가이드의 개념은 베어러, API 키 및 OAuth 정의가 실제 요청에 어떻게 매핑되는지 설명합니다.

특정 폴더에만 헤더를 적용하려는 경우

전역 매개변수는 전체 프로젝트에 영향을 미칩니다. 때로는 너무 광범위할 수 있습니다. 예를 들어, /admin 엔드포인트만 X-Admin-Scope 헤더를 필요로 하고 나머지 프로젝트는 이를 포함해서는 안 되는 경우입니다.

솔직한 한계는 다음과 같습니다: Apidog는 폴더 설정에 기본 "헤더 추가" 필드를 가지고 있지 않습니다. 채울 폴더 수준 헤더 UI가 없습니다. 대신 문서에서 설명하는 것은 폴더 수준에서 사전 요청 스크립트를 사용하는 해결 방법이며, 해당 폴더 내의 모든 요청이 헤더를 상속하도록 합니다. 이 스크립트는 Postman 호환 pm.* 스크립팅을 사용합니다:

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });

이를 폴더의 사전 요청 스크립트로 추가하면, 폴더 내의 모든 요청은 해당 헤더를 가져오지만 폴더 외부의 요청은 그렇지 않습니다. 이는 설정 토글이 아닌 스크립트이므로, 기본 경로가 아닌 폴더 범위의 요구 사항에 대한 의도적인 대체 방식으로 다루십시오. 이 스크립트가 기반이 되는 더 넓은 스크립팅 모델에 대해서는 Apidog의 사전 요청 및 사후 요청 스크립트 사용 방법 가이드를 참조하십시오.

어떤 지렛대를 언제 사용할 것인가

이제 엔드포인트를 편집하지 않고 헤더를 첨부하는 세 가지 방법이 있습니다. 범위별로 선택하세요:

환경 관리를 통한 전역 매개변수 (헤더): 헤더가 전체 프로젝트에 적용됩니다. 이는 공유 인증 헤더 또는 버전 헤더의 기본값입니다.
환경 변수 ({{token}}): 전역 매개변수와 함께 사용하여 헤더 슬롯은 전역적이지만 비밀은 안전하게 저장되고 환경별로 교체됩니다.
폴더 수준 사전 요청 스크립트 (pm.request.headers.add): 헤더가 단일 폴더에만 적용됩니다. 프로젝트 전반에 걸친 적용이 너무 광범위할 때 이 방법을 사용하세요.

몇 가지 주의할 점이 있습니다. 두 개의 전역 헤더가 충돌하지 않도록 중복 매개변수 이름을 확인하고, 각 매개변수의 유형이 사용 방식과 일치하는지 확인하세요. 그리고 우선순위 규칙을 기억하세요: 자체 Authorization을 설정하는 엔드포인트는 전역 헤더를 재정의합니다. 이는 한 경로가 다른 토큰을 필요로 할 때 유용한 기능이지만, 해당 경로에 자체 값이 있다는 사실을 잊었다면 놀랄 수 있습니다. 이 세 가지 기능 중 어느 것도 문서에 요금제 제한이 명시되어 있지 않으므로, 특정 티어가 없어도 사용할 수 있습니다.

Apidog CLI로 워크플로우 자동화

전역 매개변수와 환경은 단순히 GUI 편의 기능이 아닙니다. 자동화된 실행에도 적용됩니다. Apidog에서 저장된 테스트 시나리오를 구축하고 명령줄에서 실행하면, 해당 실행은 ID로 전달하는 환경을 상속받으므로, GUI에서 작동했던 동일한 Bearer {{token}} 헤더와 X-Api-Version 값은 CI에서도 동일하게 해결됩니다.

CLI(Node.js v16+)를 설치하고 인증합니다:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

그런 다음 특정 환경에 대해 저장된 시나리오를 실행합니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

-e 플래그는 환경을 선택하므로, 시나리오는 토큰을 포함하여 해당 환경의 변수를 가져옵니다. -t 플래그는 테스트 시나리오 ID이고 -r은 리포터(cli, html 또는 junit)입니다. 이것이 바로 연결점입니다: 헤더와 변수를 한 번 정의하면, CLI를 통해 실행되는 모든 시나리오가 이를 포함하게 됩니다. 설정 및 토큰 세부 정보는 Apidog CLI 설치 가이드를 참조하고, 자동화에 실행을 연결하려면 GitHub Actions의 Apidog CLI 안내서에서 전체 파이프라인을 보여줍니다.

자주 묻는 질문

전역 매개변수가 특정 엔드포인트에 설정한 헤더를 재정의하나요?

아니요. 전역 매개변수는 엔드포인트 수준 매개변수보다 우선순위가 낮습니다. 요청이 자체 Authorization 헤더를 정의하면 해당 값이 우선하고 해당 요청에 대한 전역 값은 무시됩니다. 전역 매개변수는 엔드포인트가 자체 값을 설정하지 않은 경우에 채워지는 프로젝트 기본값으로 작동합니다.

실제 토큰을 일반 텍스트로 저장하지 않으려면 어디에 저장해야 하나요?

원시 기본값 대신 환경 변수 또는 전역 변수를 사용하십시오. 전역 헤더를 Bearer {{token}}으로 설정하고, 실제 비밀은 ≡ 환경 아이콘을 통해 생성된 변수에 보관하십시오. 문서는 토큰이 인라인으로 저장되지 않도록 민감한 데이터에 대해 변수 또는 보안 방법을 사용할 것을 권장합니다. JSONPath를 사용하여 변수 추출하기에 대한 저희 가이드는 로그인 응답에서 토큰을 캡처하여 동일한 방식으로 재사용하는 방법을 다룹니다.

전역 헤더가 실제로 전송되었는지 어떻게 확인할 수 있나요?

아무 요청이나 보낸 다음 응답 콘솔에서 실제 요청(Actual Request) 탭을 엽니다. 이 탭은 {{token}} 및 기타 변수가 이미 해당 값으로 대체된 채로 요청이 실제로 전송된 방식을 보여줍니다. 헤더가 거기에 나타나면 실제로 전송된 것입니다.

전체 프로젝트가 아닌 단일 폴더에만 기본 헤더를 추가할 수 있나요?

예, 하지만 설정 필드를 통해서는 불가능합니다. Apidog에는 기본 폴더 헤더 UI가 없기 때문입니다. pm.request.headers.add({ key, value })를 사용하여 폴더에 사전 요청 스크립트를 추가하면 해당 폴더의 모든 요청은 헤더를 상속하지만 프로젝트의 나머지 부분은 그렇지 않습니다.

전역 매개변수 또는 환경 변수를 사용하려면 유료 요금제가 필요한가요?

이러한 기능에 대한 문서에는 어떤 티어 제한도 명시되어 있지 않습니다. 전역 매개변수, 환경 변수 및 폴더 수준 사전 요청 스크립트는 모두 무료 대 유료 게이트 없이 문서화되어 있습니다.

마무리

Apidog에서 모든 요청에 헤더를 설정하는 것은 한 번만 하면 되는 작업입니다: 환경 관리에서 헤더를 전역 매개변수로 정의하고, 비밀을 일반 텍스트에 노출되지 않도록 {{token}} 변수로 참조하며, 실제 요청 탭을 통해 전송 여부를 확인합니다. 특정 폴더에만 헤더가 필요한 경우, 사전 요청 스크립트 대체가 이를 처리합니다. 본인의 프로젝트에서 따라 하려면 Apidog를 다운로드하고 첫 번째 전역 헤더를 설정해 보세요. 무료이며 신용 카드가 필요 없습니다.

button