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

아티클
06/14/2024

보고서 쿼리 언어 사양

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

보고서 쿼리 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

쿼리 매개 변수

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 만들기

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

요청 구문

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

요청 헤더

헤더	형식	설명
권한 부여	string	필수입니다. 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 형식이어야 합니다.	문자열

참고 항목

보고서를 만드는 동안에는 필수 항목 중 RecurrenceCount 하나 EndTime 또는 조합 RecurrenceInterval 이 필요합니다.

샘플 응답

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

응답 코드: '''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	보고서를 만드는 동안 요청 페이로드에 제공된 이름
설명	보고서를 만드는 동안 요청 페이로드에 제공된 설명
QueryId	보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 ID
쿼리	이 보고서에 대해 실행될 쿼리 텍스트
사용자	보고서를 만드는 데 사용되는 사용자 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	보고서를 만드는 동안 요청 페이로드에 제공된 콜백 메서드
형식	보고서를 만드는 동안 요청 페이로드에 제공된 보고서 파일의 형식
EndTime	보고서를 만드는 동안 요청 페이로드에 제공된 종료 시간입니다. 이 값은 다음으로 설정된 경우에만 `ExecuteNow` 적용됩니다. `True`
TotalRecurrenceCount	`RecurrenceCount` 보고서를 만드는 동안 요청 페이로드에 제공됨
nextExecutionStartTime	다음 보고서 실행이 시작되는 UTC 타임스탬프
TotalCount	값 배열의 레코드 수
StatusCode	결과 코드입니다. 가능한 값은 200, 400, 401, 403, 500입니다
message	API 실행의 상태 메시지

보고서 실행 API 가져오기

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

Important

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

요청 구문

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

요청 헤더

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

경로 매개 변수

None

쿼리 매개 변수

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

요청 페이로드

None

샘플 응답

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

응답 코드: 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 실행의 상태 메시지

다음을 통해 공유

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

보고서 쿼리 언어 사양

보고서 쿼리 API 만들기

요청 구문

요청 헤더

경로 매개 변수

쿼리 매개 변수

요청 페이로드 예제

용어 설명

샘플 응답

용어 설명

보고서 API 만들기

요청 구문

요청 헤더

경로 매개 변수

쿼리 매개 변수

요청 페이로드 예제

용어 설명

샘플 응답

응답 페이로드

용어 설명

보고서 실행 API 가져오기

요청 구문

요청 헤더

경로 매개 변수

쿼리 매개 변수

요청 페이로드

샘플 응답

응답 페이로드 예제

용어 설명

피드백

추가 리소스