통합 문서 매개 변수
매개 변수를 사용하여 소비자로부터 입력을 수집하고 통합 문서의 다른 부분에서 참조할 수 있습니다. 일반적으로 결과 집합의 범위를 지정하거나 올바른 시각적 개체를 설정하는 데 사용됩니다. 이 핵심 기능을 사용하여 대화형 보고서와 환경을 빌드할 수 있습니다.
통합 문서를 사용할 때 매개 변수 컨트롤이 소비자에게 표시되는 방식을 제어할 수 있습니다. 텍스트 상자 대 드롭다운 목록, 단일 선택 대 다중 선택, 텍스트, JSON, KQL 또는 Azure Resource Graph의 값일 수 있습니다.
다음 매개 변수 유형을 지원합니다.
- 시간: 미리 채워진 시간 범위에서 선택하거나 사용자 지정 범위를 선택할 수 있습니다.
- 드롭다운: 값 또는 값 집합에서 선택할 수 있습니다.
- 옵션 그룹: 알려진 집합에서 하나의 값을 선택할 수 있습니다.
- 텍스트: 임의의 텍스트를 입력할 수 있습니다.
- 조건: 이전에 지정된 매개 변수를 기반으로 조건 집합을 정의할 수 있습니다. 매개 변수는 동적 값을 제공하기 위해 평가됩니다.
- 리소스: 하나 이상의 Azure 리소스를 선택할 수 있습니다.
- 구독: 하나 이상의 Azure 구독 리소스를 선택할 수 있습니다.
- 다중 값: 하나 이상의 임의 텍스트 값을 설정할 수 있습니다.
- 리소스 종류: 하나 이상의 Azure 리소스 종류 값을 선택할 수 있습니다.
- 위치: 하나 이상의 Azure 위치 값을 선택할 수 있습니다.
매개 변수 참조
바인딩 또는 값 확장을 사용하여 통합 문서의 다른 부분에서 매개 변수 값을 참조할 수 있습니다.
바인딩을 사용하여 매개 변수 참조
이 예에서는 바인딩을 사용하여 시간 범위 매개 변수를 참조하는 방법을 보여 줍니다.
쿼리 추가를 선택하여 쿼리 제어를 추가한 다음 Application Insights 리소스를 선택합니다.
시간 범위 드롭다운 목록을 열고 하단의 매개 변수 섹션에서 시간 범위 옵션을 선택합니다.
- 이 옵션은 시간 범위 매개 변수를 차트의 시간 범위에 바인딩합니다.
- 샘플 쿼리의 시간 범위는 이제 지난 24시간입니다.
쿼리를 실행하여 결과를 확인합니다.
KQL을 사용하여 매개 변수 참조
이 예에서는 KQL을 사용하여 시간 범위 매개 변수를 참조하는 방법을 보여 줍니다.
쿼리 추가를 선택하여 쿼리 제어를 추가한 다음 Application Insights 리소스를 선택합니다.
KQL에서
| where timestamp {TimeRange}매개 변수를 사용하여 시간 범위 필터를 입력합니다.- 이 매개 변수는 쿼리 평가 시간을
| where timestamp > ago(1d)로 확장합니다. - 이 옵션은 매개 변수의 시간 범위 값입니다.
- 이 매개 변수는 쿼리 평가 시간을
쿼리를 실행하여 결과를 확인합니다.
텍스트를 사용하여 매개 변수 참조
이 예에서는 텍스트로 시간 범위 매개 변수를 참조하는 방법을 보여 줍니다.
- 통합 문서에 텍스트 컨트롤을 추가합니다.
- Markdown에서
The chosen time range is {TimeRange:label}을 입력합니다. - 편집 완료를 선택합니다.
- 텍스트 컨트롤에 선택한 시간 범위는 지난 24시간입니다라는 텍스트가 표시됩니다.
매개 변수 형식 지정 옵션
각 매개 변수 유형에는 고유한 형식 지정 옵션이 있습니다. 매개 변수의 형식 확장 옵션을 보려면 매개 변수 편집 창의 미리 보기 섹션을 사용합니다.
이러한 옵션을 사용하여 시간 범위 선택기를 제외한 모든 매개 변수 유형의 형식을 지정할 수 있습니다. 시간 형식 지정의 예제는 시간 매개 변수 옵션을 참조하세요.
다른 매개 변수 형식은 다음과 같습니다.
- 리소스 선택기: 리소스 ID의 형식이 지정됩니다.
- 구독 선택기: 구독 값의 형식이 지정됩니다.
toml을 json으로 변환
구문: {param:tomltojson}
원래 값:
name = "Sam Green"
[address]
state = "New York"
country = "USA"
형식이 지정된 값:
{
"name": "Sam Green",
"address": {
"state": "New York",
"country": "USA"
}
}
JSON 이스케이프
구문: {param:escapejson}
원래 값:
{
"name": "Sam Green",
"address": {
"state": "New York",
"country": "USA"
}
}
형식이 지정된 값:
{\r\n\t\"name\": \"Sam Green\",\r\n\t\"address\": {\r\n\t\t\"state\": \"New York\",\r\n\t\t\"country\": \"USA\"\r\n }\r\n}
텍스트를 base64로 인코딩
구문: {param:base64}
원래 값:
Sample text to test base64 encoding
형식이 지정된 값:
U2FtcGxlIHRleHQgdG8gdGVzdCBiYXNlNjQgZW5jb2Rpbmc=
JSONPath를 사용하여 매개 변수 형식 지정
JSON 콘텐츠인 문자열 매개 변수의 경우 매개 변수 형식 문자열에서 JSONPath를 사용할 수 있습니다.
예를 들어 다음 값이 있는 시각화에서 쿼리 또는 선택의 결과인 selection이라는 문자열 매개 변수가 있을 수 있습니다.
{ "series":"Failures", "x": 5, "y": 10 }
JSONPath를 사용하면 해당 개체에서 개별 값을 가져올 수 있습니다.
| 형식 | 결과 |
|---|---|
{selection:$.series} |
Failures |
{selection:$.x} |
5 |
{selection:$.y} |
10 |
참고 항목
매개 변수 값이 유효한 JSON이 아닌 경우 형식의 결과는 빈 값이 됩니다.
매개 변수 스타일
매개 변수에 사용할 수 있는 스타일은 다음과 같습니다.
알약
알약 스타일이 기본 스타일입니다. 매개 변수는 텍스트처럼 보이며 편집 모드로 전환하려면 사용자가 매개 변수를 한 번 선택해야 합니다.
Standard
표준 스타일에서 컨트롤은 항상 표시되며, 해당 컨트롤의 위쪽에 레이블이 있습니다.
가로 양식
가로 양식 스타일에서 컨트롤은 항상 표시되며 레이블은 컨트롤의 왼쪽에 있습니다.
세로 양식
세로 양식 스타일에서 컨트롤은 항상 표시되며 레이블은 컨트롤 위에 있습니다. 표준 스타일과 달리 한 행에는 하나의 레이블 또는 컨트롤만 있습니다.
참고 항목
표준, 가로 양식 및 세로 양식 레이아웃에는 인라인 편집의 개념이 없습니다. 컨트롤은 항상 편집 모드에 있습니다.
글로벌 매개 변수
이제 매개 변수가 작동하는 방식과 매개 변수가 설정된 위치의 "다운스트림" 매개 변수만 사용할 수 있다는 제한 사항을 알아보았으므로 이러한 규칙을 변경하는 전역 매개 변수에 대해 알아봅니다.
전역 매개 변수를 사용하는 경우에도 매개 변수를 사용하려면 먼저 선언해야 합니다. 그러나 해당 매개 변수에 값을 설정하는 모든 단계는 통합 문서에 있는 해당 매개 변수의 모든 인스턴스에 영향을 미칩니다.
참고 항목
전역 매개 변수를 변경하면 이 "모두 업데이트" 동작이 있으므로 이 동작이 필요한 매개 변수에 대해서만 전역 설정을 켜야 합니다. 서로 종속된 전역 매개 변수의 조합은 경쟁하는 전역 매개 변수에서 서로를 반복하여 변경하는 주기 또는 진동을 만들 수 있습니다. 순환을 피하기 위해 전역으로 선언된 매개 변수를 "재선언"할 수 없습니다. 이름이 같은 매개 변수의 후속 선언은 해당 위치에서 편집할 수 없는 읽기 전용 매개 변수를 만듭니다.
전역 매개 변수의 일반적인 사용은 다음과 같습니다.
여러 차트 간의 시간 범위 동기화:
- 전역 매개 변수가 없으면 차트의 모든 시간 범위 브러시는 해당 차트 이후에만 내보내집니다. 따라서 세 번째 차트에서 시간 범위를 선택하면 네 번째 차트만 업데이트됩니다.
- 전역 매개 변수를 사용하면 전역 timeRange 매개 변수를 만들고 기본값을 지정하여 다른 모든 차트에서 이를 경계 시간 범위 및 시간 브러시 출력으로 사용하도록 할 수 있습니다. 또한 범위가 브러싱된 경우에만 매개 변수 내보내기 설정을 지정합니다. 차트에서 시간 범위를 변경하면 통합 문서 상단의 전역 timeRange 매개 변수가 업데이트됩니다. 이 기능을 사용하여 통합 문서가 대시보드처럼 작동하도록 할 수 있습니다.
링크 또는 단추를 통해 링크 단계에서 선택한 탭 변경 허용:
- 전역 매개 변수를 사용하지 않으면 링크 단계에서 선택한 탭에 대한 매개 변수만 출력합니다.
- 전역 매개 변수를 사용하면 전역 selectedTab 매개 변수를 만들 수 있습니다. 그런 다음 링크 단계의 탭 선택에서 해당 매개 변수 이름을 사용할 수 있습니다. 해당 매개 변수 값을 링크에서 통합 문서로 전달하거나 다른 단추 또는 링크를 사용하여 선택한 탭을 변경할 수 있습니다. 이러한 방식으로 링크 단계의 단추를 사용하면 마법사와 같은 환경을 만들 수 있습니다. 여기서 단계 아래쪽의 단추는 위에 표시되는 섹션에 영향을 줄 수 있습니다.
전역 매개 변수 만들기
매개 변수 단계에서 매개 변수를 만들 때 고급 설정에서 이 매개 변수를 전역으로 처리 옵션을 사용합니다. 전역 매개 변수를 만드는 유일한 방법은 매개 변수 단계를 사용하여 이를 선언하는 것입니다. 선택, 브러싱, 링크, 단추 및 탭을 통해 매개 변수를 만드는 다른 방법은 전역 매개 변수만 업데이트할 수 있습니다. 스스로는 선언할 수 없습니다.
매개 변수가 사용 가능하고 일반 매개 변수처럼 작동합니다.
기존 전역 매개 변수 값 업데이트
차트 예에서 전역 매개 변수를 업데이트하는 가장 일반적인 방법은 시간 브러싱을 사용하는 것입니다.
이 예에서 timerange 매개 변수는 전역으로 선언됩니다. 그 아래의 쿼리 단계에서 쿼리에서 해당 timerange 매개 변수를 사용하고 시간 차트 결과를 반환하는 쿼리를 만들고 실행합니다. 쿼리 단계의 고급 설정에서 시간 범위 브러싱 설정을 사용하도록 설정합니다. 시간 브러시 매개 변수의 출력과 동일한 매개 변수 이름을 사용합니다. 또한 범위가 브러싱된 경우에만 매개 변수 내보내기 옵션을 선택합니다.
이 차트에서 시간 범위를 브러싱할 때마다 이 쿼리 위의 timerange 매개 변수와 쿼리 단계 자체도 업데이트됩니다. 이는 timerange에도 의존하기 때문입니다.
브러싱 전:
- 시간 범위가 지난 1시간으로 표시됩니다.
- 차트에 지난 1시간의 데이터가 표시됩니다.
브러싱 중:
- 시간 범위는 여전히 지난 1시간으로 설정되어 있으며 브러싱 윤곽이 그려집니다.
- 변경된 매개 변수가 없습니다. 브러시를 놓으면 시간 범위가 업데이트됩니다.
브러싱 후:
- 이 단계에서 시간 브러시로 지정된 시간 범위를 설정합니다. 전역 값을 재정의합니다. 이제 시간 범위 드롭다운 목록에 해당 사용자 지정 시간 범위가 표시됩니다.
- 상단의 전역 값이 변경되었고 이 차트는 timerange를 입력으로 사용하므로 차트에 사용된 쿼리의 시간 범위도 업데이트됩니다. 결과적으로 쿼리와 차트가 업데이트됩니다.
- timerange에 의존하는 통합 문서의 다른 모든 단계도 업데이트됩니다.
참고 항목
전역 매개 변수를 사용하지 않는 경우 timerange 매개 변수 값은 이 쿼리 단계 아래에서만 변경됩니다. 이 단계 위의 항목 또는 이 항목 자체는 업데이트되지 않습니다.