Marketplace 요금제 청구 API
요금제 청구 API는 게시자가 파트너 센터에 게시할 제품에 대한 사용자 지정 계량 차원을 만들 때 사용해야 합니다. 사용량 이벤트를 발생시키기 위해 커스텀 차원을 가진 하나 이상의 플랜이 포함된 구매 제안에는 측정된 청구 API와의 통합이 필요합니다.
중요하다
코드의 사용량을 추적하고 기본 요금을 초과하는 사용량에 대해서만 사용 이벤트를 Microsoft로 보내야 합니다.
SaaS에 대한 사용자 지정 계량 차원을 만드는 방법에 대한 자세한 내용은 SaaS 요금제 청구참조하세요.
관리되는 앱 계획을 사용하여 Azure 애플리케이션 제품에 대한 사용자 지정 계량 차원을 만드는 방법에 대한 자세한 내용은 Azure 애플리케이션 제품 설정 세부 정보구성을 참조하세요.
TLS 1.2 참고 적용
TLS 버전 1.2 버전은 HTTPS 통신을 위한 최소 버전으로 적용됩니다. 코드에서 이 TLS 버전을 사용해야 합니다. TLS 버전 1.0 및 1.1은 더 이상 사용되지 않으며 연결 시도가 거부됩니다.
계량 청구 단일 사용 사례
특정 고객이 구매한 플랜에 대한 활성 리소스(구독)에 대해 사용 이벤트를 내보내려면 게시자가 사용 이벤트 API를 호출해야 합니다. 사용 이벤트는 제품을 게시할 때 게시자가 정의한 계획의 각 사용자 지정 차원에 대해 별도로 내보내집니다.
자원 및 차원당 달력 일의 각 시간에 대해 하나의 사용 이벤트만 내보낼 수 있습니다. 한 시간에 둘 이상의 단위를 사용하는 경우 해당 시간에 사용된 모든 단위를 누적한 다음 단일 이벤트에서 내보낸다. 사용량 이벤트는 지난 24시간 동안만 내보낼 수 있습니다. 8:00~8:59:59 사이에 언제든지 사용 이벤트를 내보내고 같은 날 8:00~8:59:59 사이에 추가 이벤트를 보내는 경우 중복으로 거부됩니다.
POST: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
쿼리 매개 변수:
| 매개 변수 | 추천 |
|---|---|
ApiVersion |
2018-08-31을 사용합니다. |
요청 헤더:
| 콘텐츠 유형 |
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 Application 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"
}
코드: 401 권한 없음. 권한 부여 토큰이 잘못되었거나 만료되었습니다. 요청이 인증 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
코드: 403 사용할 수 없습니다. 권한 부여 토큰이 잘못되었거나, 제공되지 않았거나, 권한이 부족하여 제공되었습니다. 유효한 권한 부여 토큰을 제공해야 합니다.
코드: 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을 사용합니다. |
요청 헤더:
| 콘텐츠 유형 |
application/json 사용 |
|---|---|
x-ms-requestid |
클라이언트에서 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
x-ms-correlationid |
클라이언트에서 작업에 대한 고유 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트와 서버 쪽의 이벤트 상관 관계를 지정합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다. |
authorization |
이 API 호출을 만드는 ISV를 식별하는 고유한 액세스 토큰입니다. 토큰 값이 게시자에 의해 검색될 때의 형식은 설명된 대로 Bearer <access_token>입니다.
|
메모
요청 본문에서 리소스 식별자는 SaaS 앱 및 사용자 지정 미터를 내보내는 Azure Managed App에 대해 서로 다른 의미를 줍니다. SaaS 앱의 리소스 식별자는 resourceID입니다. Azure Application Managed Apps 계획의 리소스 식별자는 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 Application Managed Apps 계획에서는 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"
}
]
}
BatchUsageEvent API 응답에서 참조되는 상태 코드에 대한 설명:
| 상태 코드 | 묘사 |
|---|---|
Accepted |
허용. |
Expired |
사용이 만료되었습니다. |
Duplicate |
제공된 중복 사용량입니다. |
Error |
오류 코드입니다. |
ResourceNotFound |
제공된 사용량 리소스가 잘못되었습니다. |
ResourceNotAuthorized |
이 리소스에 대한 사용 권한을 제공할 권한이 없습니다. |
ResourceNotActive |
리소스가 일시 중단되었거나 활성화되지 않았습니다. |
InvalidDimension |
사용량이 전달되는 차원이 이 제품/플랜에 유효하지 않습니다. |
InvalidQuantity |
전달된 수량이 0보다 작거나 같습니다. |
BadArgument |
입력이 없거나 형식이 잘못되었습니다. |
코드: 400
잘못된 요청입니다. 일괄 처리에는 25개 이상의 사용 이벤트가 포함되었습니다.
코드: 401 권한 없음. 권한 부여 토큰이 잘못되었거나 만료되었습니다. 요청이 인증 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
코드: 403 사용할 수 없습니다. 권한 부여 토큰이 잘못되었거나, 제공되지 않았거나, 권한이 부족하여 제공되었습니다. 유효한 권한 부여 토큰을 제공해야 합니다.
종량제 청구 사용 이력 조회
사용 이벤트 API를 호출하여 사용 이벤트 목록을 가져올 수 있습니다. ISV는 이 API를 사용하여 구성 가능한 특정 기간 동안 게시된 사용 이벤트와 이러한 이벤트가 API 호출 시점에 있는 상태를 확인할 수 있습니다.
GET: https://marketplaceapi.microsoft.com/api/usageEvents
쿼리 매개 변수:
| 매개 변수 | 추천 |
|---|---|
| ApiVersion | 2018-08-31을 사용합니다. |
| 사용 시작 날짜 | ISO8601 형식의 DateTime입니다. 예를 들어 2020-12-03T15:00 또는 2020-12-03 |
| UsageEndDate(선택 사항) | ISO8601 형식의 DateTime입니다. 기본값 = 현재 날짜 |
| offerId(선택 사항) | 기본값 = 사용 가능한 모든 항목 |
| planId(선택 사항) | 기본값 = 사용 가능한 모든 항목 |
| 차원(선택 사항) | 기본값 = 사용 가능한 모든 항목 |
| azureSubscriptionId(선택 사항) | 기본값 = 모든 가능한 항목 |
| reconStatus(선택 사항) | 기본값 = 사용 가능한 모든 항목 |
reconStatus가능한 값은 다음과 같습니다.
| ReconStatus | 묘사 |
|---|---|
| 제출 | PC 분석에서 아직 처리되지 않음 |
| 허용 | PC 분석과 일치됨 |
| 거부됨 | 파이프라인에서 거부되었습니다. 원인을 조사하려면 Microsoft 지원에 문의하세요. |
| 불일치 | MarketplaceAPI 및 파트너 센터 분석 수량은 모두 0이 아니지만 일치하지 않습니다. |
요청 헤더:
| 콘텐츠 형식 | 애플리케이션/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
}
]
상태 코드
코드: 401 권한 없음. 권한 부여 토큰이 잘못되었거나 만료되었습니다. 요청이 인증 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.
코드: 403 사용할 수 없습니다. 권한 부여 토큰이 잘못되었거나, 제공되지 않았거나, 권한이 부족하여 제공되었습니다. 유효한 권한 부여 토큰을 제공해야 합니다.
개발 및 테스트 모범 사례
사용자 지정 미터 배출을 테스트하려면 계량 API와의 통합을 구현하고 단위당 가격이 0인 사용자 지정 차원이 정의된 게시된 SaaS 제품에 대한 계획을 만듭니다. 또한 제한된 사용자만 통합에 액세스하고 테스트할 수 있도록 이 제품을 미리 보기로 게시합니다.
또한 기존 라이브 제품에 대한 프라이빗 플랜을 사용하여 테스트하는 동안 이 계획에 대한 액세스를 제한된 대상으로 제한할 수 있습니다.
지원 받기
파트너 센터 상업용 Marketplace 프로그램에 대한 지원의 지침에 따라 게시자 지원 옵션을 이해하고 Microsoft에서 지원 티켓을 엽니다.
관련 콘텐츠
계량 서비스 API에 대한 자세한 내용은 Marketplace 계량 서비스 API FAQ참조하세요.