Marketplace 요금제 청구 API
요금 청구 API는 게시자가 파트너 센터에 게시할 제품에 대한 사용자 지정 계량 차원을 만들 때 사용해야 합니다. 요금제 청구 API와의 통합은 사용 이벤트를 내보내기 위해 사용자 지정 차원이 있는 하나 이상의 플랜이 있는 구매한 제품에 필요합니다.
Important
코드의 사용량을 추적하고 기본 요금보다 높은 사용량에 한해 사용량 이벤트를 Microsoft로 보내야 합니다.
SaaS에 대한 사용자 지정 계량 차원을 만드는 방법에 대한 자세한 내용은 SaaS 요금제 청구를 참조 하세요.
관리되는 앱 계획을 사용하여 Azure 애플리케이션 제품에 대한 사용자 지정 계량 차원을 만드는 방법에 대한 자세한 내용은 Azure 애플리케이션 제품 설정 세부 정보 구성을 참조하세요.
TLS 1.2 참고 적용
TLS 버전 1.2 버전은 HTTPS 통신을 위한 최소 버전으로 적용됩니다. 코드에서 이 TLS 버전을 사용해야 합니다. TLS 버전 1.0 및 1.1은 더 이상 사용되지 않으며 연결 시도가 거부됩니다.
요금제 청구 단일 사용 이벤트
특정 고객이 구매한 플랜에 대한 활성 리소스(구독)에 대해 사용 이벤트를 내보내려면 게시자가 사용 이벤트 API를 호출해야 합니다. 사용 이벤트는 제품을 게시할 때 게시자가 정의한 계획의 각 사용자 지정 차원에 대해 별도로 내보내집니다.
리소스 및 차원당 달력상의 각 시간에 대해 하나의 사용 이벤트만 내보낼 수 있습니다. 한 시간에 둘 이상의 단위를 사용하는 경우 해당 시간에 사용된 모든 단위를 누적한 다음 단일 이벤트에서 내보낸다. 지난 24시간의 사용 이벤트만 내보낼 수 있습니다. 8시에서 8시 59분 59초 사이에 아무 때나 사용 이벤트를 내보내고(수락됨) 같은 날 8시에서 8시 59분 59초 사이에 추가 이벤트를 보내면 중복으로 거부됩니다.
POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 추천 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
요청 헤더:
| Content-type | application/json 사용 |
|---|---|
x-ms-requestid |
클라이언트에서 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값을 제공하지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
x-ms-correlationid |
클라이언트에서 작업에 대한 고유 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
authorization |
이 API 호출을 만드는 ISV를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" 게시자가 설명한 대로 토큰 값을 검색하는 경우입니다.
|
요청 본문 예제:
{
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
Azure 애플리케이션 Managed Apps 계획의 resourceId 경우 관리되는 앱resource group Id입니다. 페치에 대한 예제 스크립트는 Azure 관리 ID 토큰을 사용하여 찾을 수 있습니다.
SaaS 제품의 resourceId 경우 SaaS 구독 ID입니다. SaaS 구독에 대한 자세한 내용은 목록 구독을 참조 하세요.
응답
코드: 200
확인. 추가 처리와 청구를 위해 Microsoft 쪽에서 사용량 내보내기를 수락하고 기록했습니다.
응답 페이로드 예제:
{
"usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // this is the only value in case of single usage event
"messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
}
코드: 400
잘못된 요청입니다.
- 제공된 요청 데이터가 없거나 잘못되었습니다.
effectiveStartTime는 과거에 24시간 이상입니다. 이벤트가 만료되었습니다.- SaaS 구독이 구독 상태가 아닙니다.
응답 페이로드 예제:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
코드: 403
금지됩니다. 권한 부여 토큰이 제공되지 않았거나, 잘못되었거나, 만료되었습니다. 또는 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품의 구독에 액세스하려고 시도합니다.
코드: 409
충돌입니다. 지정된 리소스 ID, 유효 사용 날짜 및 시간에 대한 사용 이벤트가 이미 보고되었습니다.
응답 페이로드 예제:
{
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
"quantity": 1.0,
"dimension": "dim1",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "plan1"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
}
요금제 청구 일괄 처리 사용 이벤트
일괄 처리 사용 이벤트 API를 사용하면 둘 이상의 구매한 리소스에 대한 사용 이벤트를 한 번에 내보냅니다. 또한 다른 일정 시간 동안 동일한 리소스에 대한 여러 사용 이벤트를 내보냅니다. 단일 일괄 처리의 최대 이벤트 수는 25개입니다.
POST: https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 추천 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
요청 헤더:
| Content-type | application/json 사용 |
|---|---|
x-ms-requestid |
클라이언트에서 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값을 제공하지 않으면 값이 하나 생성된 후 응답 헤더에 제공됩니다. |
x-ms-correlationid |
클라이언트에서 작업에 대한 고유 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값을 제공하지 않으면 값이 하나 생성된 후 응답 헤더에 제공됩니다. |
authorization |
이 API 호출을 만드는 ISV를 식별하는 고유한 액세스 토큰입니다. 형식은 Bearer <access_token> 게시자가 설명한 대로 토큰 값을 검색하는 경우입니다.
|
참고 항목
요청 본문에서 리소스 식별자는 SaaS 앱과 사용자 지정 미터를 내보내는 Azure 관리형 앱에 대해 서로 다른 의미를 줍니다. SaaS 앱의 리소스 식별자는 resourceID입니다. Azure 애플리케이션 관리형 앱 플랜의 리소스 식별자는 resourceUri입니다. 리소스 식별자에 대한 자세한 내용은 Azure Marketplace 요금제 청구 - 사용량 이벤트를 제출할 때 올바른 ID 선택을 참조하세요.
SaaS 제품의 resourceId 경우 SaaS 구독 ID입니다. SaaS 구독에 대한 자세한 내용은 목록 구독을 참조 하세요.
SaaS 앱에 대한 요청 본문 예제:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
Azure 애플리케이션 관리형 앱 플랜의 경우 resourceUri는 관리형 애플리케이션 resourceUsageId입니다. 페치에 대한 예제 스크립트는 Azure 관리 ID 토큰을 사용하여 찾을 수 있습니다.
Azure 애플리케이션 관리형 앱에 대한 요청 본문 예제:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
]
}
응답
코드: 200
확인. 추가 처리 및 청구를 위해 일괄 처리 사용량 배출이 허용되고 Microsoft 쪽에 기록되었습니다. 응답 목록은 일괄 처리의 각 개별 이벤트에 대한 상태와 함께 반환됩니다. 응답 페이로드를 반복하여 일괄 처리 이벤트의 일부로 전송된 각 개별 사용 이벤트에 대한 응답을 이해해야 합니다.
응답 페이로드 예제:
{
"count": 2, // number of records in the response
"result": [
{ // first response
"usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // see list of possible statuses below,
"messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
"resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
},
{ // second response
"status": "Duplicate",
"messageTime": "0001-01-01T00:00:00",
"error": {
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>",
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
},
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
]
}
API 응답에서 참조되는 상태 코드에 BatchUsageEvent 대한 설명:
| 상태 코드 | 설명 |
|---|---|
Accepted |
허용. |
Expired |
사용이 만료되었습니다. |
Duplicate |
제공된 중복 사용량입니다. |
Error |
오류 코드 |
ResourceNotFound |
제공된 사용량 리소스가 잘못되었습니다. |
ResourceNotAuthorized |
이 리소스에 대한 사용 권한을 제공할 권한이 없습니다. |
ResourceNotActive |
리소스가 일시 중단되었거나 활성화되지 않았습니다. |
InvalidDimension |
사용량이 전달된 차원이 이 제품/계획에 적합하지 않습니다. |
InvalidQuantity |
전달된 수량이 0보다 작거나 같습니다. |
BadArgument |
입력이 없거나 형식이 잘못되었습니다. |
코드: 400
잘못된 요청입니다. 일괄 처리에는 25개 이상의 사용 이벤트가 포함되었습니다.
코드: 403
금지됩니다. 권한 부여 토큰이 제공되지 않았거나, 잘못되었거나, 만료되었습니다. 또는 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품의 구독에 액세스하려고 시도합니다.
요금제 청구 사용량 이벤트 검색
사용량 이벤트 API를 호출하여 사용량 이벤트 목록을 가져올 수 있습니다. ISV는 이 API를 사용하여 특정 구성 가능한 기간 동안 게시된 사용량 이벤트와 API 호출 시점에 이러한 이벤트가 있는 상태를 확인할 수 있습니다.
가져오기: https://marketplaceapi.microsoft.com/api/usageEvents
쿼리 매개 변수:
| 매개 변수 | 추천 |
|---|---|
| ApiVersion | 2018-08-31을 사용합니다. |
| usageStartDate | ISO8601 형식의 DateTime입니다. 예를 들어 2020-12-03T15:00 또는 2020-12-03 |
| UsageEndDate(선택 사항) | ISO8601 형식의 DateTime입니다. 기본값 = 현재 날짜 |
| offerId(선택 사항) | 기본값 = 모두 사용 가능 |
| planId(선택 사항) | 기본값 = 모두 사용 가능 |
| 차원(선택 사항) | 기본값 = 모두 사용 가능 |
| azureSubscriptionId(선택 사항) | 기본값 = 모두 사용 가능 |
| reconStatus(선택 사항) | 기본값 = 모두 사용 가능 |
reconStatus의 가능한 값:
| ReconStatus | 설명 |
|---|---|
| 제출됨 | PC Analytics에서 아직 처리되지 않음 |
| Accepted | PC 분석과 일치 |
| 거부됨 | 파이프라인에서 거부됨 원인을 조사하려면 Microsoft 지원에 문의하세요. |
| 불일치 | MarketplaceAPI 및 파트너 센터 분석 수량은 모두 0이 아니지만 일치하지 않습니다. |
요청 헤더:
| 내용 유형 | application/json 사용 |
|---|---|
| x-ms-requestid | 클라이언트의 요청을 추적하기 위한 고유한 문자열 값(기본적으로 GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
| x-ms-correlationid | 클라이언트에서 작업에 대한 고유 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
| 권한 | 이 API 호출을 만드는 ISV를 식별하는 고유한 액세스 토큰입니다. 게시자가 토큰 값을 검색하는 경우 형식은 Bearer <access_token>입니다. 자세한 내용은 다음을 참조하세요.
|
응답
응답 페이로드 예제:
수락됨*
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Accepted",
"submittedQuantity": 17.0,
"processedQuantity": 17.0,
"submittedCount": 17
}
]
제출됨
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Submitted",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
불일치
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Mismatch",
"submittedQuantity": 17.0,
"processedQuantity": 16.0,
"submittedCount": 17
}
]
거부됨
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Rejected",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
상태 코드
코드: 403 사용할 수 없음. 권한 부여 토큰이 제공되지 않았거나, 잘못되었거나, 만료되었습니다. 또는 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품의 구독에 액세스하려고 시도합니다.
개발 및 테스트 모범 사례
사용자 지정 미터 배출을 테스트하려면 계량 API와의 통합을 구현하고 단위당 가격이 0인 사용자 지정 차원이 정의된 게시된 SaaS 제품에 대한 계획을 만듭니다. 또한 제한된 사용자만 통합에 액세스하고 테스트할 수 있도록 이 제품을 미리 보기로 게시합니다.
제한된 대상 그룹에 대해 테스트하는 동안 기존 라이브 제품의 프라이빗 플랜을 사용하여 이 플랜에 대한 액세스를 제한할 수도 있습니다.
지원 받기
게시자 지원 옵션을 파악하고 Microsoft에서 지원 티켓을 열려면 파트너 센터의 상업용 Marketplace 프로그램 지원의 지침을 따르세요.
관련 콘텐츠
계량 서비스 API에 대한 자세한 내용은 Marketplace 계량 서비스 API FAQ를 참조하세요.