상업용 마켓플레이스를 위한 프로그램 방식의 접근 방식

이 다이어그램은 새 보고서 템플릿을 만들고, 사용자 지정 보고서를 예약하고, 실패 데이터를 검색하는 데 사용되는 API 호출 패턴을 보여 줍니다.

그림 1: API 호출 패턴 개략적인 흐름

이 목록은 그림 1에 대한 자세한 내용을 제공합니다.

1. 클라이언트 애플리케이션은 보고서 쿼리 만들기 API호출하여 사용자 지정 보고서 스키마/템플릿을 정의할 수 있습니다. 또는 시스템 쿼리 목록에서 보고서 템플릿(QueryId)을 사용할 수 있습니다.
2. 성공하면 보고서 템플릿 만들기 API는 QueryId반환합니다.
3. 그런 다음 클라이언트 애플리케이션은 보고서 시작 날짜, 반복 간격, 되풀이 및 선택적 콜백 URI와 함께 QueryID 사용하여 보고서 만들기 API 호출합니다.
4. 성공하면 보고서 만들기 APIReportID반환합니다.
5. 클라이언트 애플리케이션은 보고서 데이터를 다운로드할 준비가 되는 즉시 콜백 URI에서 알림을 받습니다.
6. 그런 다음 클라이언트 애플리케이션은 보고서 실행 가져오기 API 사용하여 Report ID 및 날짜 범위로 보고서의 상태를 쿼리합니다.
7. 성공하면 보고서 다운로드 링크가 반환되고 애플리케이션에서 데이터 다운로드를 시작할 수 있습니다.

보고서 쿼리 언어 사양

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

보고서 쿼리 API 만들기

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

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

다음 예제에서는 사용자 지정 쿼리를 만들어 지난 달의 ISVUsage 데이터 세트에서 유료 SKU 대한 정규화된 사용량 및 예상 재무 요금을 가져오는 방법을 보여 줍니다.

요청 구문

요청 헤더

Path 매개 변수

없음

Query 매개 변수

없음

요청 페이로드 예제

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

용어집

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

샘플 응답

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

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

응답 페이로드 예제:

{
  "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

용어집

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

보고서 API 만들기

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

요청 구문

요청 헤더

Path 매개 변수

없음

Query 매개 변수

없음

요청 페이로드 예제

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

용어집

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

샘플 응답

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

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

응답 페이로드:

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "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
}

용어집

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

보고서 실행 API 가져오기

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

요청 구문

요청 헤더

Path 매개 변수

없음

Query 매개 변수

요청 페이로드

없음

샘플 응답

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

응답 코드: 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 표시됩니다. reportAccessSecureLinkURL을 선택하여 보고서를 다운로드할 수 있습니다.

용어집

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

Swagger API URL통해 API를 사용해 볼 수 있습니다.

관련 콘텐츠

• Marketplace Insights 보고서에 대한 첫 번째 API 호출