상업용 Marketplace의 프로그래밍 방식 액세스 패러다임

아티클
01/24/2024

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

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

이 목록에는 그림 1에 대한 자세한 내용이 나와 있습니다.

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

보고서 쿼리 언어 사양

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

보고서 쿼리 API 만들기

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

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

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

요청 구문

메서드	요청 URI
게시	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

요청 헤더

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

경로 매개 변수

None

쿼리 매개 변수

None

요청 페이로드 예제

{
    "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"
}

용어 설명

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

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

참고 항목

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

샘플 응답

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

응답 코드: 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
}

용어 설명

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

매개 변수	설명
`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://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

요청 헤더

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

경로 매개 변수

None

쿼리 매개 변수

None

요청 페이로드 예제

{
  "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",
}

용어 설명

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

매개 변수	필수	설명	허용된 값
`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": "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
}

용어 설명

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

매개 변수	설명
`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`	보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 시작 시간입니다. 이는 "True"로 설정된 경우에만 `ExecuteNow` 적용됩니다.
`queryEndTime`	보고서를 만드는 동안 요청 페이로드에 제공된 쿼리 종료 시간입니다. 이는 "True"로 설정된 경우에만 `ExecuteNow` 적용됩니다.
`StartTime`	보고서를 만드는 동안 요청 페이로드에 제공된 시작 시간
`ReportStatus`	보고서 실행의 상태입니다. 가능한 값은 Paused, Active 및 Inactive입니다.
`RecurrenceInterval`	보고서를 만드는 동안 요청 페이로드에 제공된 되풀이 간격
`RecurrenceCount`	보고서의 되풀이 횟수 다시 기본
`CallbackUrl`	보고서를 만드는 동안 요청 페이로드에 제공된 콜백 URL
`CallbackMethod`	보고서를 만드는 동안 요청 페이로드에 제공된 콜백 메서드
`Format`	보고서를 만드는 동안 요청 페이로드에 제공된 보고서 파일의 형식
`EndTime`	보고서를 만드는 동안 요청 페이로드에 제공된 종료 시간입니다. 이는 "True"로 설정된 경우에만 `ExecuteNow` 적용됩니다.
`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://api.partnercenter.microsoft.com/insights/v1.1/cmp/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` 만 세부 정보를 가져옵니다. 다중 `executionIds` 항목은 세미콜론 ";"으로 구분하여 지정할 수 있습니다.
`executionStatus`	아니요	string/enum	필터를 사용하여 이 인수에 지정된 보고서 `executionStatus` 만 세부 정보를 가져옵니다. 유효한 값은 `Pending`, `Running`, `Paused` 및 `Completed`입니다. 기본값은 `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`	보고서 실행 인스턴스의 상태입니다. 유효한 값은 `Pending`, `Running`, `Paused` 및 `Completed`입니다.
`ReportLocation`	보고서가 다운로드되는 위치입니다.
`ReportAccessSecureLink`	보고서를 안전하게 액세스할 수 있는 링크
`ReportExpiryTime`	보고서 링크가 만료되는 UTC 시간(yyyy-MM-ddTHH:mm:ssZ 형식)
`ReportGeneratedTime`	보고서가 생성된 UTC 시간: yyyy-MM-ddTHH:mm:ssZ
`EndTime`	보고서를 만드는 동안 요청 페이로드에 제공된 종료 시간입니다. 이는 "True"로 설정된 경우에만 `ExecuteNow` 적용됩니다.
`TotalRecurrenceCount`	`RecurrenceCount` 보고서를 만드는 동안 요청 페이로드에 제공됨
`nextExecutionStartTime`	다음 보고서 실행이 시작되는 UTC 타임스탬프
`TotalCount`	값 배열의 데이터 집합 수
`StatusCode`	결과 코드 가능한 값은 200, 400, 401, 403, 404 및 500입니다.
`message`	API 실행의 상태 메시지

다음 단계

Swagger API URL을 통해 API를 사용해 볼 수 있습니다.
Marketplace Insights 보고서에 대한 첫 번째 API 호출

다음을 통해 공유

상업용 Marketplace의 프로그래밍 방식 액세스 패러다임

보고서 쿼리 언어 사양

보고서 쿼리 API 만들기

보고서 API 만들기

보고서 실행 API 가져오기

다음 단계

피드백

피드백

추가 리소스