다음을 통해 공유

프로그래밍 방식 액세스 패러다임 - 앱 및 게임 API

보고서 쿼리 언어 사양

보고서를 만드는 데 사용할 수 있는 시스템 쿼리를 제공하지만 비즈니스 요구 사항에 따라 사용자 고유의 쿼리를 만들 수도 있습니다. 사용자 지정 쿼리에 대한 자세한 내용은 사용자 지정 쿼리 사양을 참조하세요.

보고서 쿼리 API 만들기

이 API는 열 및 메트릭을 내보내야 하는 데이터 세트를 정의하는 사용자 지정 쿼리를 만드는 데 도움이 됩니다. API는 비즈니스 요구 사항에 따라 새 보고 템플릿을 만들 수 있는 유연성을 제공합니다.

제공하는 시스템 쿼리를 사용할 수도 있습니다 . 사용자 지정 보고서 템플릿이 필요하지 않은 경우 제공하는 시스템 쿼리의 QueryIds를 사용하여 보고서 만들기 API를 직접 호출할 수 있습니다.

요청 구문

메서드 요청 URI
게시 https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries

요청 헤더

헤더 유형 설명
권한 부여 string 필수입니다. Microsoft Entra 액세스 토큰입니다. 형식은 Bearer <token>입니다.
콘텐츠-종류 string application/JSON

경로 매개 변수

없음

쿼리 매개 변수

None

요청 페이로드 예제

{
    "Name": "PurchaseQuery",
    "Description": "Fetch Purchase related dataset",
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily"
}

용어 설명

이 표에서는 요청 페이로드의 요소에 대한 주요 정의를 제공합니다.

매개 변수 필수 설명 허용된 값
Name 예 쿼리의 사용자 친화적인 이름 string
Description 아니요 만든 쿼리에 대한 설명 string
Query 예 비즈니스 요구 사항에 따라 문자열 쿼리 string

참고

사용자 지정 쿼리 예제는 샘플 쿼리를 참조 하세요.

샘플 응답

응답 페이로드는 다음과 같이 구성됩니다.

응답 코드: 200, 400, 401, 403, 500

응답 페이로드 예제:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " PurchaseQuery ",
            "description": " Fetch Purchase related dataset",
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

용어 설명

이 표에서는 응답에 있는 요소의 주요 정의를 제공합니다.

매개 변수 설명
QueryId 만든 쿼리의 UUID(범용 고유 식별자)
Name 쿼리를 만드는 동안 요청 페이로드에 제공된 이름
Description 쿼리를 만드는 동안 요청 페이로드에 제공된 설명
Query 쿼리를 만드는 동안 요청 페이로드에 제공된 사용자 지정 보고서 쿼리
Type userDefined을(를) 수동으로 만든 쿼리에 대해 설정하십시오.
User 쿼리를 만드는 데 사용되는 사용자 ID
CreatedTime 쿼리를 만든 UTC 시간입니다. 형식: yyyy-MM-ddTHH:mm:ssZ
TotalCount 값 배열의 레코드 수
StatusCode 결과 코드
가능한 값은 200, 400, 401, 403, 500입니다
message API 실행의 상태 메시지

보고서 API 만들기

사용자 지정 보고서 템플릿을 성공적으로 만들고 Create Report Query 응답의 일부로 QueryID을 수신하면, 이 API를 호출하여 쿼리가 정기적으로 실행되도록 예약할 수 있습니다. 보고서를 배달할 빈도 및 일정을 설정할 수 있습니다. 제공하는 시스템 쿼리의 경우 QueryId를 사용하여 보고서 만들기 API를 호출할 수도 있습니다.

요청 구문

메서드 요청 URI
게시 https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport

요청 헤더

헤더 유형 설명
권한 부여 문자열 필수입니다. Microsoft Entra 액세스 토큰입니다. 형식은 Bearer <token>입니다.
콘텐츠 유형 string application/JSON

경로 매개 변수

None

쿼리 매개 변수

None

요청 페이로드 예제

{ 
    "Name": "PurchaseQuery", 
    "Description": "Fetch Purchase related dataset", 
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily" 
}

용어 설명

이 표에서는 요청 페이로드의 요소에 대한 주요 정의를 제공합니다.

매개 변수 필수 설명 허용된 값
ReportName 예 보고서에 할당된 사용자 친화적인 이름 문자열
Description 아니요 만든 보고서에 대한 설명 문자열
QueryId 예 보고서 생성에 사용해야 하는 쿼리 ID 문자열
StartTime 예 보고서 생성이 시작되는 UTC 타임스탬프입니다. yyyy-MM-ddTHH:mm:ssZ 형식이어야 합니다. 문자열
ExecuteNow 아니요 이 매개 변수는 한 번만 실행되는 보고서를 만드는 데 사용해야 합니다. StartTime, RecurrenceInterval, RecurrenceCount및 EndTime 로 설정하면 무시됩니다. true Boolean
QueryStartTime 아니요 필요에 따라 데이터를 추출하는 쿼리의 시작 시간을 지정합니다. 이 매개변수는 ExecuteNow가 true으로 설정된 일회성 실행 보고서에만 적용됩니다. yyyy-MM-ddTHH:mm:ssZ 형식이어야 합니다. 문자열로 타임스탬프
QueryEndTime 아니요 필요에 따라 데이터를 추출하는 쿼리의 종료 시간을 지정합니다. 이 매개 변수는 ExecuteNow이(가) true로 설정된 단일 실행 보고서에만 적용됩니다. yyyy-MM-ddTHH:mm:ssZ 형식이어야 합니다. 문자열로 타임스탬프
RecurrenceInterval 예 보고서를 생성해야 하는 시간 단위의 빈도입니다. 최소값은 1이고 최대값은 17520입니다. 정수
RecurrenceCount 예 생성할 보고서 수입니다. 제한은 되풀이 간격에 따라 달라집니다. 정수
Format 아니요 내보낸 파일의 파일 형식입니다. 기본 형식은 CSV입니다. CSV/TSV
CallbackUrl 아니요 선택적으로 콜백 대상으로 구성할 수 있는 공개적으로 액세스할 수 있는 URL 문자열
CallbackMethod 아니요 콜백 URL로 구성할 수 있는 Get/Post 메서드 GET/POST
EndTime 예 보고서 생성이 종료되는 UTC 타임스탬프입니다. yyyy-MM-ddTHH:mm:ssZ 형식이어야 합니다. 문자열

참고

보고서를 만드는 동안, EndTime 또는 RecurrenceInterval와 RecurrenceCount의 조합 중 하나가 필요합니다.

샘플 응답

응답 페이로드는 다음과 같이 구성됩니다.

응답 코드: '''200, 400, 401, 403, 404, 500''

응답 페이로드

{ 
  "Value": [ 
    { 
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003", 
            "reportName": " PurchaseQuery ", 
            "description": " Fetch Purchase related dataset" 
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "142344300", 
            "createdTime": "2024-01-06T05:46:00Z", 
            "modifiedTime": null, 
            "startTime": "2024-01-06T19:00:00Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": 48, 
            "recurrenceCount": 20, 
            "callbackUrl": "https://<SampleCallbackUrl>", 
            "callbackMethod": "GET", 
            "format": "csv" 
    } 
  ], 
  "TotalCount": 1, 
  "Message": "Report created successfully", 
  "StatusCode": 200 
}

용어 설명

이 표에서는 응답에 있는 요소의 주요 정의를 제공합니다.

매개 변수 설명
ReportId 만든 보고서의 UUID(범용 고유 식별자)
ReportName 보고서를 만드는 동안 요청 페이로드에 제공된 이름
Description 보고서를 만드는 동안 요청 페이로드에 제공된 설명
QueryId 보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 ID
Query 이 보고서에 대해 실행될 쿼리 텍스트
User 보고서를 만드는 데 사용되는 사용자 ID
CreatedTime 보고서가 생성된 UTC 시간(yyyy-MM-ddTHH:mm:ssZ 형식)
ModifiedTime 보고서가 마지막으로 수정된 UTC 시간: yyyy-MM-ddTHH:mm:ssZ
ExecuteNow 보고서를 만드는 동안 요청 페이로드에 제공된 ExecuteNow 매개 변수
queryStartTime 보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 시작 시간입니다. 이 값은 ExecuteNow이(가) True로 설정된 경우에만 적용됩니다.
queryEndTime 보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 종료 시간입니다. ExecuteNow가 True로 설정된 경우에만 해당됩니다.
StartTime 보고서를 만드는 동안 요청 페이로드에 제공된 시작 시간
ReportStatus 보고서 실행의 상태입니다. 가능한 값은 Paused, Active 및 Inactive입니다.
RecurrenceInterval 보고서를 만드는 동안 요청 페이로드에 제공된 되풀이 간격
RecurrenceCount 보고서의 나머지 되풀이 횟수
CallbackUrl 보고서를 만드는 동안 요청 페이로드에 제공된 콜백 URL
CallbackMethod 보고서를 만드는 동안 요청 페이로드에 제공된 콜백 메서드
Format 보고서를 만드는 동안 요청 페이로드에 제공된 보고서 파일의 형식
EndTime 보고서를 만드는 동안 요청 페이로드에 제공된 종료 시간입니다. ExecuteNow이 True로 설정된 경우에만 적용됩니다.
TotalRecurrenceCount RecurrenceCount 보고서를 만드는 동안 요청 페이로드에 제공됨
nextExecutionStartTime 다음 보고서 실행이 시작되는 UTC 타임스탬프
TotalCount 값 배열의 레코드 수
StatusCode 결과 코드입니다. 가능한 값은 200, 400, 401, 403, 500입니다
message API 실행의 상태 메시지

보고서 실행 API 가져오기

이 메서드를 사용하여 보고서 만들기 API에서 받은 보고서를 사용하여 ReportId 보고서 실행 상태를 쿼리할 수 있습니다. 보고서를 다운로드할 준비가 되면 이 메서드는 보고서 다운로드 링크를 반환합니다. 그렇지 않으면 메서드가 상태를 반환합니다. 또한 이 API를 사용하여 특정 보고서에 대해 발생한 모든 실행을 가져올 수도 있습니다.

중요

이 API는 executionStatus=Completed 및 getLatestExecution=true에 기본 쿼리 매개 변수가 설정되어 있습니다. 따라서 보고서를 처음 성공적으로 실행하기 전에 API를 호출하면 404가 반환됩니다. executionStatus=Pending을(를) 설정하여 보류 중인 실행을 가져올 수 있습니다.

요청 구문

메서드 요청 URI
가져오기 https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}

요청 헤더

헤더 형식 설명
권한 부여 string 필수입니다. Microsoft Entra 액세스 토큰입니다. 형식은 Bearer <token>입니다.
내용 유형 문자열 application/json

경로 매개 변수

None

쿼리 매개 변수

매개 변수 이름 필수 유형 설명
보고서ID 예 string 이 인수에 지정된 보고서 reportId 만 실행 세부 정보를 가져오기 위해 필터링합니다.
executionId 아니요 string 인수로 지정된 executionId 보고서의 세부 정보만 얻기 위해 필터링합니다.
실행 상태 아니요 string/enum 이 인수에 주어진 보고서 executionStatus의 세부 정보만 필터링하여 가져옵니다.
유효한 값은 다음과 PendingRunningPausedFailedCompleted같습니다.
기본값은 Completed입니다.
최신 실행 가져오기 아니요 Boolean API는 최신 보고서 실행에 대한 세부 정보를 반환합니다.
이 매개 변수는 기본적으로 true로 설정됩니다. 이 매개 변수 false의 값을 전달하도록 선택하면 API는 지난 90일 실행 인스턴스를 반환합니다.

요청 페이로드

없음

샘플 응답

응답 페이로드는 다음과 같이 구성됩니다.

응답 코드: 200, 400, 401, 403, 404, 500

응답 페이로드 예제

{
    "value": [
        {
            "executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

보고서 실행이 완료되면 실행 상태가 .로 Completed표시됩니다. reportAccessSecureLink에서 URL을 선택하여 보고서를 다운로드할 수 있습니다.

용어 설명

응답의 요소에 대한 주요 정의입니다.

매개 변수 설명
ExecutionId 실행 인스턴스의 UUID(범용 고유 식별자)
ReportId 실행 인스턴스와 연결된 보고서 ID
RecurrenceInterval 보고서를 만드는 동안 제공된 되풀이 간격
RecurrenceCount 보고서를 만드는 동안 제공된 되풀이 횟수
CallbackUrl 실행 인스턴스와 연결된 콜백 URL
CallbackMethod 보고서를 만드는 동안 요청 페이로드에 제공된 콜백 메서드
Format 실행이 끝날 때 생성된 파일의 형식
ExecutionStatus 보고서 실행 인스턴스의 상태입니다.
유효한 값은 다음과 PendingRunningPausedFailed 같습니다.Completed
ReportLocation 보고서가 다운로드되는 위치
ReportAccessSecureLink 보고서를 안전하게 액세스할 수 있는 링크
ReportExpiryTime 보고서 링크가 만료되는 UTC 시간(yyyy-MM-ddTHH:mm:ssZ 형식)
ReportGeneratedTime 보고서가 생성된 UTC 시간: yyyy-MM-ddTHH:mm:ssZ
EndTime 보고서를 만드는 동안 요청 페이로드에 제공된 종료 시간입니다. ExecuteNow이 True로 설정된 경우에만 적용됩니다.
TotalRecurrenceCount RecurrenceCount 보고서를 만드는 동안 요청 페이로드에 제공됨
nextExecutionStartTime 다음 보고서 실행이 시작되는 UTC 타임스탬프
TotalCount 값 배열의 데이터 집합 수
StatusCode 결과 코드
가능한 값은 200, 400, 401, 403, 404 및 500입니다.
message API 실행의 상태 메시지
  • Last updated on