Michael Johnson분석 데이터 세트의 스키마에 JSON 열 attributes가 있지만 키가 계정 데이터에 따라 달라지는 경우, 이제 Cloudflare 인트로스펙션을 통해 해당 키를 찾을 수 있습니다. 2026년 10월 27일 업데이트로 include_attributes=true 매개변수가 추가되어, 응답에 직전 7일 동안 계정 데이터에서 발견된 키와 유형이 나열됩니다.
개발자에게 이는 구체적인 문제를 해결해 줍니다. 필터를 작성하기 전에 선택한 데이터 세트에 실제로 어떤 필드가 있는지 확인할 수 있습니다. 기존 이름인 include_custom_attributes와 custom_attributes도 당분간 작동하지만, Cloudflare는 이를 사용 중단 예정으로 표시했습니다. 새로운 통합은 업데이트된 SQL API 인트로스펙션을 기반으로 구축하는 것이 좋습니다.
인트로스펙션이 반환하는 내용
일부 Cloudflare Analytics 데이터 세트는 attributes 열에 추가적인 키-값 쌍을 저장합니다. 새 매개변수를 사용하는 인트로스펙션은 7일간의 데이터를 바탕으로 키와 유형을 파악하고, 데이터 세트 객체의 attributes 필드에 해당 정보를 반환합니다. 이는 최근 계정 기록에서 추론한 스키마로, SQL 쿼리를 준비하는 데 도움이 됩니다.
Cloudflare의 공식 예시는 /client/v4/analytics/sql/introspection 경로를 사용하고 계정 식별자와 events.httpRequests 데이터 세트 이름을 전달하며, 속성 검색을 활성화합니다.
curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
--data-urlencode "dataset_name=events.httpRequests" \
--data-urlencode "include_attributes=true"실행하기 전에 환경에서 CLOUDFLARE_API_TOKEN 및 CLOUDFLARE_ACCOUNT_TAG 변수를 설정하세요. 토큰은 bearer 인증 정보로 전달됩니다. 예시에 나온 변수 이름은 팀의 로컬 설정이며 Cloudflare의 별도 매개변수가 아닙니다.
발견한 키를 쿼리에 사용하기
인트로스펙션 후 원하는 데이터 세트의 설명에서 attributes 필드를 확인하고 실제로 나열된 키를 선택하세요. Cloudflare는 JSON 열의 키를 정확하게 참조하는 예로 attributes['http.method']를 보여줍니다. 이벤트 이름만 보고 키를 추측하지 말고, 발견된 이름을 필터에 사용하세요.
실무에서는 다음 순서로 진행할 수 있습니다.
include_attributes=true를 지정해 필요한 데이터 세트의 인트로스펙션을 요청합니다.- 반환된
attributes필드의 키와 유형을 확인 날짜와 함께 저장합니다. attributes['http.method']와 같이 정확한 키 이름을 사용해 쿼리를 작성합니다.- 계정 데이터로 쿼리를 검증하고, 스키마나 들어오는 이벤트의 특성이 달라지면 키를 다시 탐색합니다.
확인 날짜는 재현성에 도움이 됩니다. Cloudflare는 7일간의 데이터를 바탕으로 속성을 추론하므로, 발견된 키 목록은 고정된 스키마가 아니라 최근 데이터를 반영합니다. 해당 기간에 필요한 키가 나타나지 않았다면, 결과에 없다는 사실만으로 그 키를 언제나 사용할 수 없다고 단정할 수는 없습니다.
기존 이름에서 마이그레이션하기
기존 코드에서는 요청 매개변수 include_custom_attributes를 include_attributes로 바꾸고, 응답 필드 custom_attributes를 처리하던 부분은 attributes를 읽도록 수정하세요. Cloudflare에 따르면 이전 이름도 계속 작동하므로, 통합을 긴급히 복구할 필요가 없다면 마이그레이션을 별도로 진행할 수 있습니다.
안전하게 전환하려면 계약의 두 부분, 즉 전송하는 쿼리 매개변수와 응답 필드의 경로를 모두 확인하세요. 그런 다음 같은 데이터 세트에 요청을 실행해 키 목록을 비교합니다. 이 테스트를 통해 새 매개변수 이름을 사용하면서 코드가 여전히 이전 응답 필드를 기다리는 흔한 마이그레이션 오류를 찾아낼 수 있습니다.
분석 파이프라인에 주는 의미
include_attributes=true를 사용하면 공식 인트로스펙션 기능으로 동적 JSON 필드를 찾을 수 있으며, 개발자는 키 이름과 함께 유형도 확인할 수 있습니다. 새 쿼리와 파서를 include_attributes 및 응답 필드 attributes에 맞춰 업데이트하고, 발견 날짜를 저장하며, 실제로 확인된 키를 기준으로 필터를 작성하세요.
