청구 및 청구되지 않은 일일 등급 사용량 조정 API v2(GA)
적용 대상: 파트너 센터(Azure Government, Azure 독일 또는 Azure 중국 21Vianet에서 사용할 수 없음)
비동기 API는 Azure Blob을 통해 청구 및 조정 데이터에 액세스하는 더 빠르고 관리하기 쉬운 방법을 제공합니다. 이러한 API를 사용하면 몇 시간 동안 연결을 열어 두거나 2,000개의 품목 일괄 처리를 반복할 필요가 없습니다.
발레 키 및 비동기 요청-회신 패턴을 사용하여 일일 등급 사용량 조정 API를 최적화했습니다. 이러한 API를 사용하는 경우 모든 특성 또는 일일 등급 사용량 조정 데이터의 하위 집합에 액세스하는 데 사용할 수 있는 토큰을 받게 됩니다.
참고 항목
새 API는 파트너 센터 API 호스트에서 호스트되지 않습니다. 대신 MICROSOFT Graph API를 사용하여 파트너 청구 데이터를 내보낼 때 MS Graph에서 찾을 수 있습니다. Microsoft Graph v1.0 | Microsoft Learn. 이러한 API에 액세스하려면 다음 세부 정보를 참조하세요.
MS Graph 퍼블릭/글로벌 클라우드에만 이러한 API를 사용할 수 있습니다. Azure Government, Azure 독일, Azure 중국 21Vianet에서는 이 API를 아직 사용할 수 없습니다.
참고 항목
베타 버전을 사용한 경우 GA(일반 공급) 버전에서 중요한 변경 내용을 알 수 없습니다. 차이점과 업데이트를 이해하려면 두 버전을 비교하는 것이 좋습니다.
Important
일일 등급 사용량에는 다음 제품에 대한 요금이 포함되지 않습니다.
- Azure 예약
- Azure 절약 플랜
- Office
- Dynamics
- Microsoft Power Apps
- 영구 소프트웨어
- 소프트웨어 구독
- 타사 SaaS 제품
API 개요
일별 등급 사용 현황 품목을 비동기적으로 검색하려면 두 개의 API 엔드포인트를 사용합니다. 프로세스는 다음과 같습니다.
사용량 줄 항목 엔드포인트
이 API를 사용하여 청구되거나 청구되지 않은 일일 등급 사용 현황 품목을 검색합니다. 위치 헤더에 202 HTTP 상태 및 URL이 표시됩니다. 매니페스트 URL을 사용하여 성공 상태 받을 때까지 정기적으로 이 URL을 폴링합니다.
엔드포인트 상태 작업
상태 성공하려면 정기적으로 이 API를 계속 호출합니다. 데이터가 준비되지 않은 경우 API 응답에는 다시 시도하기 전에 대기 시간을 알려주는 Retry-After 헤더가 포함됩니다. 작업이 완료되면 사용량 현황 데이터를 다운로드할 수 있는 스토리지 폴더가 있는 매니페스트 리소스를 가져옵니다. 응답은 최적화된 처리량 및 I/O 병렬 처리를 위해 파일을 더 작은 조각으로 분할합니다.
시퀀스 다이어그램
다음은 조정 데이터를 다운로드하는 단계를 보여 주는 시퀀스 다이어그램입니다.
사용자 작업 순서
일일 등급 사용량 조정 품목을 검색하려면 다음 단계를 수행합니다.
1단계: 요청 제출
API 엔드포인트에 POST 요청을 제출합니다.
청구되지 않은 일일 등급 사용 현황 품목 가져오기
현재 또는 지난 달 또는 청구 기간에 대한 청구되지 않은 일일 등급 사용 현황 품목을 가져옵니다.
API 요청
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Accept: application/json
Content-Type: application/json
{
"currencyCode": "USD",
"billingPeriod": "current",
"attributeSet": "basic"
}
요청 본문
| 특성 | 필수 | Type | 설명 |
|---|---|---|---|
| attributeSet | False | 문자열 | 모든 특성에 대해 "full"을 선택하거나 제한된 집합에 대해 "기본"을 선택합니다. 기본값은 "full"입니다. (여기에서 특성 목록을 참조하세요). 선택 사항. |
| billingPeriod | True | 문자열 | "현재" 또는 "마지막"(V1 API의 "이전"과 동일)을 사용하여 현재 또는 지난 달 또는 청구 기간에 대한 일일 등급 사용량을 가져옵니다. 필수입니다. |
| currencyCode | True | 문자열 | 파트너 청구 통화 코드입니다. 필수입니다. |
요청 헤더
API에 대한 헤더를 요청하려면 안정성 및 지원을 참조하세요.
API 응답
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
API를 사용하는 경우 일반적으로 HTTP 202 상태 반환합니다. 요청에 따라 다른 가능한 상태 보려면 표준 API 응답 상태 참조하세요.
| 코드 | 설명 |
|---|---|
| 202 – 수락됨 | 요청이 수락되었습니다. 요청의 상태 검사 위치 헤더에 제공된 URL을 쿼리합니다. |
청구된 일일 정격 사용 현황 품목 가져오기
마감된 청구 기간 동안 청구서에 대한 청구된 일일 등급 사용량 품목을 가져옵니다.
API 요청
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
쿼리 매개 변수
해당 없음
요청 본문
| 특성 | 필수 | Type | 설명 |
|---|---|---|---|
| invoiceId | True | 문자열 | 각 청구서에 대한 고유 식별자입니다. 필수입니다. |
| attributeSet | False | 문자열 | 모든 특성에 대해 "full"을 선택하거나 제한된 집합에 대해 "기본"을 선택합니다. 기본값은 "full"입니다. (여기에서 특성 목록을 참조하세요). 선택 사항. |
요청 헤더
API에 대한 요청 헤더입니다. 자세한 내용은 안정성 및 지원을 참조하세요.
API 응답
HTTP/1.1 202 수락됨
위치: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
API를 사용하는 경우 일반적으로 HTTP 202 상태 반환합니다. 요청에 따라 가능한 다른 상태 상태를 참조하세요.
| 코드 | 설명 |
|---|---|
| 202 – 수락됨 | 요청이 수락되었습니다. 요청의 상태 검사 위치 헤더에 제공된 URL을 쿼리합니다. |
2단계: 요청 상태 확인
요청의 상태 검사 "성공" 또는 "실패"상태 있는 HTTP 200 응답을 기다립니다. 요청이 성공하면 매니페스트 URL이 "resourceLocation" 특성에 제공됩니다.
작업 상태 가져오기
요청의 상태 검색합니다.
API 요청
요청 매개 변수
| 속성 | 다음 포함 | 필수 | Type | 설명 |
|---|---|---|---|---|
| operationId | 요청 URI | True | 문자열 | 요청 상태 검사 고유 ID입니다. 필수입니다. |
요청 헤더
API에 대한 헤더를 요청하려면 안정성 및 지원을 참조하세요.
요청 본문
해당 없음.
응답 상태
표준 HTTP 상태 외에도 API는 다음 HTTP 상태 반환할 수 있습니다.
| 코드 | 설명 |
|---|---|
| 410 – 사라지다 | 매니페스트 링크는 서버에서 설정한 특정 기간 동안만 활성화됩니다. 이 시간이 경과한 후에는 매니페스트에 액세스하기 위한 새 요청을 제출해야 합니다. |
응답 페이로드
API 응답 페이로드에는 다음 특성이 포함됩니다.
| 특성 | 필수 | 설명 |
|---|---|---|
| id | True | 각 응답에 대한 고유 ID입니다. 필수입니다. |
| status | True | 값 및 작업 (필수): notstarted: "Retry-After" 헤더에 지정된 시간 동안 기다린 다음 다른 호출을 수행하여 상태 검사. running: "Retry-After" 헤더에 지정된 시간 동안 기다린 다음 다른 호출을 수행하여 상태 검사. 성공: 데이터가 준비되었습니다. resourceLocation에 지정된 URI를 사용하여 매니페스트 페이로드를 검색합니다. 실패: 작업이 영구적으로 실패했습니다. 다시 시작합니다. |
| createdDateTime | True | 요청이 이루어진 시간입니다. 필수입니다. |
| lastActionDateTime | True | 상태 마지막으로 변경된 시간입니다. 필수입니다. |
| resourceLocation | False | 매니페스트 페이로드의 URI입니다. 선택 사항. |
| error | False | 작업이 실패하면 오류 세부 정보가 JSON 형식으로 제공됩니다. 선택 사항. 다음 특성이 포함될 수 있습니다. 메시지 (필수): 오류에 대한 자세한 설명입니다. 코드 (필수): 발생한 오류 유형입니다. |
리소스 위치 개체
| 특성 | 설명 |
|---|---|
| id | 매니페스트의 고유 식별자입니다. |
| schemaVersion | 매니페스트 스키마의 버전입니다. |
| dataFormat | 청구 데이터 파일의 형식입니다. compressedJSON: 각 Blob이 JSON 줄 형식의 데이터를 포함하는 압축 파일인 데이터 형식입니다. 각 Blob에서 데이터를 검색하려면 압축을 해제합니다. |
| createdDateTime | 매니페스트 파일을 만든 날짜 및 시간입니다. |
| eTag | 매니페스트 데이터의 버전입니다. 청구 정보가 변경되어 새 값이 생성됩니다. |
| partnerTenantId | 파트너 테넌트의 ID입니다. |
| rootDirectory | 파일의 루트 디렉터리입니다. |
| sasToken | 디렉터리 아래의 모든 파일을 읽을 수 있는 SAS(공유 액세스 서명) 토큰입니다. |
| partitionType | "partitionValue" 특성에 따라 데이터를 여러 Blob으로 나눕니다. 시스템에서 지원되는 수를 초과하는 파티션을 분할합니다. 기본적으로 데이터는 파일의 줄 항목 수에 따라 분할됩니다. 이러한 값이 변경될 수 있으므로 코드에서 고정된 수의 줄 항목 또는 파일 크기를 설정하지 마세요. |
| blobCount | 이 파트너 테넌트 ID의 총 파일 수입니다. |
| blobs | 파트너 테넌트 ID에 대한 파일 세부 정보를 포함하는 "Blob" 개체의 JSON 배열입니다. |
| Blob 개체 | 다음 세부 정보를 포함하는 개체입니다. |
| name | Blob의 이름입니다. |
| partitionValue | 파일을 포함하는 파티션입니다. 큰 파티션은 여러 파일로 분할되며 각 파일에는 동일한 "partitionValue"가 포함됩니다. |
API 요청
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API 응답
응답은 데이터를 처리할 때 다시 시도하기 전에 10초 동안 대기하는 것이 좋습니다.
HTTP/1.1 200 OK
Retry-After: 10
{
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-05Z",
"status": "running"
}
API 요청
(이전 요청 후 10초 후...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API 응답
API는 "succeeded" 상태 및 "resourceLocation"에 대한 URI를 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",
"@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",
"id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",
"createdDateTime": "2023-12-05T21:17:29Z",
"lastActionDateTime": "2023-12-05T21:18:00.8897902Z",
"status": "succeeded",
"resourceLocation": {
"id": "44e8500b-ab92-490e-8ac3-90500a1d3427",
"createdDateTime": "2023-11-06T19:58:47.513Z",
"schemaVersion": "2",
"dataFormat": "compressedJSON",
"partitionType": "default",
"eTag": "RwDrn7fbiTXy6UULE",
"partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",
"rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",
"sasToken": "{token}",
"blobCount": 1,
"blobs": \[
{
"name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",
"partitionValue": "default"
}
\]
}
}
3단계: Azure Blob Storage에서 일일 등급 사용량 조정 품목 다운로드
"sasToken" 및 "rootDirectory"에서 SAS(공유 액세스 서명) 토큰 및 Blob Storage 위치를 가져오면 매니페스트 페이로드 API 응답이 속성됩니다. Azure Storage SDK/도구를 사용하여 Blob 파일을 다운로드하고 압축을 풉니다. JSONLines 형식입니다.
표준 API 응답 상태
API 응답에서 다음 HTTP 상태 수신할 수 있습니다.
| ‘코드’ | 설명 |
|---|---|
| 400 - 잘못된 요청 | 요청이 없거나 잘못된 데이터가 포함되어 있습니다. 오류 세부 정보는 응답 본문을 확인합니다. |
| 401 - 권한 없음 | 호출자는 인증되지 않으며, 첫 번째 호출을 하기 전에 파트너 API 서비스로 인증해야 합니다. |
| 403 - 사용 권한 없음 | 요청을 만드는 데 필요한 권한 부여가 없습니다. |
| 404 – 찾을 수 없음 | 요청된 리소스는 제공된 입력 매개 변수와 함께 사용할 수 없습니다. |
| 410 – 사라지다 | 매니페스트 링크 시간이 초과되었거나 만료되었습니다. 새 요청을 제출합니다. |
| 500 – 내부 서버 오류 | API 또는 해당 종속성 중 하나가 지금 요청을 수행할 수 없습니다. 나중에 다시 시도하세요. |
베타 및 GA 버전 비교
베타 버전과 일반 공급(GA) 버전 간의 차이점을 이해하려면 비교 표를 참조하세요. 베타 버전을 사용하는 경우 GA 버전으로 전환하는 것은 간단합니다.
| 중요 정보 | 베타 | 일반적으로 사용 가능 |
|---|---|---|
| API 호스트 엔드포인트 | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP 메서드 | 게시 | 게시 |
| 청구되지 않는 일일 등급 사용량 API 엔드포인트 | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| 청구되지 않은 일일 정격 사용량 API에 대한 입력 매개 변수 | API 요청에 매개 변수를 지정하려면 요청 URL의 쿼리 문자열에 매개 변수를 포함합니다. 예를 들어 기간 및 currencyCode 매개 변수를 지정하려면 요청 URL에 추가 ?period=current¤cyCode=usd 합니다. |
입력을 제공하려면 요청 본문에 JSON 개체를 포함합니다. JSON 개체에는 다음 속성이 포함되어야 합니다. * currencyCode: 청구서의 통화 코드입니다. 예를 들어 USD입니다. * billingPeriod: 청구서의 청구 기간입니다. 예를 들어 현재입니다. 다음은 currencyCode 및 billingPeriod 속성을 포함하는 JSON 개체의 예입니다. <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| 청구된 일일 정격 사용량 API 엔드포인트 | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| 청구된 일일 정격 사용량 API에 대한 입력 매개 변수 | API 요청에 매개 변수를 지정하려면 요청 URL에 invoiceId를 포함합니다. 또한 쿼리 문자열에 선택적 조각 매개 변수를 포함하여 전체 특성 집합을 검색할 수 있습니다. 예를 들어 전체 특성 집합을 검색하려면 요청 URL에 추가 ?fragment=full 합니다. |
입력을 제공하려면 요청 본문에 JSON 개체를 포함합니다. JSON 개체에는 다음 속성이 포함되어야 합니다. * invoiceId: 청구서의 ID입니다. 예를 들어 G00012345. * attributeSet: 응답에 포함할 특성 집합입니다. 예를 들어 전체입니다. 다음은 invoiceId 및 attributeSet 속성을 포함하는 JSON 개체의 예입니다. {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| 매니페스트 리소스 | 별도의 GET /manifests/{id} 메서드를 사용하여 매니페스트 리소스를 검색합니다. | GET /operations/{Id} 메서드를 사용합니다. 이 메서드는 resourceLocation에서 관련 매니페스트 리소스를 반환하므로 GET /manifests/{id} 메서드에 대한 별도의 호출이 필요하지 않습니다. |
| 매니페스트 스키마 변경 | ||
| "id": 사용할 수 없음 | "id": 매니페스트 리소스의 고유 식별자입니다. | |
| "version": 사용 가능 | "version": 이름이 "schemaversion"으로 변경되었습니다. | |
| "dataFormat": 사용 가능 | "dataFormat": 사용할 수 있습니다. | |
| "utcCretedDateTime": 사용 가능 | "utcCretedDateTime": 이름이 "createdDateTime"으로 변경되었습니다. | |
| "eTag": 사용 가능 | "eTag": 사용할 수 있습니다. | |
| "partnerTenantId": 사용 가능 | "partnerTenantId": 사용 가능 | |
| "rootFolder": 사용 가능 | "rootFolder": 이름이 "rootDirectory"로 바뀌었습니다. | |
| "rootFolderSAS": 사용 가능 | "rootFolderSAS": 이름이 "sasToken"으로 바뀌었습니다. 이제 토큰을 제공하고 더 이상 루트 디렉터리 경로를 포함하지 않습니다. 디렉터리에 액세스하려면 대신 "rootDirectory" 속성을 사용합니다. | |
| "partitionType": 사용 가능 | "partitionType": 사용할 수 있습니다. | |
| "blobCount": 사용 가능 | "blobCount": 사용할 수 있습니다. | |
| "sizeInBytes": 사용 가능 | "sizeInBytes": 사용할 수 없습니다. | |
| "Blob": 사용 가능 | "Blob": 사용할 수 있습니다. | |
| "Blob 개체": 사용 가능 | "Blob 개체": 사용할 수 있습니다. | |
| "name": 사용 가능 | "name": 사용할 수 있습니다. | |
| "partitionValue": 사용 가능 | "partitionValue": 사용할 수 있습니다. |
일일 등급 사용량 조정 품목 특성
"전체" 또는 "기본" 특성 집합에 대한 일일 정격 사용량 조정 API에서 반환된 특성을 비교하려면 다음 정보를 참조하세요.
| 특성 | 전체 | Basic |
|---|---|---|
| PartnerId | 예 | 예 |
| PartnerName | 예 | 예 |
| 고객 ID | 예 | 예 |
| CustomerName | 예 | 예 |
| CustomerDo기본Name | 예 | 아니요 |
| CustomerCountry | 예 | 아니요 |
| MpnId | 예 | 아니요 |
| Tier2MpnId | 예 | 아니요 |
| InvoiceNumber | 예 | 예 |
| ProductId | 예 | 예 |
| SkuId | 예 | 예 |
| AvailabilityId | 예 | 아니요 |
| SkuName | 예 | 예 |
| ProductName | 예 | 아니요 |
| PublisherName | 예 | 예 |
| PublisherId | 예 | 아니요 |
| SubscriptionDescription | 예 | 아니요 |
| SubscriptionId | 예 | 예 |
| ChargeStartDate | 예 | 예 |
| ChargeEndDate | 예 | 예 |
| UsageDate | 예 | 예 |
| MeterType | 예 | 아니요 |
| MeterCategory | 예 | 아니요 |
| MeterId | 예 | 아니요 |
| MeterSubCategory | 예 | 아니요 |
| MeterName | 예 | 아니요 |
| MeterRegion | 예 | 아니요 |
| 단위 | 예 | 예 |
| ResourceLocation | 예 | 아니요 |
| ConsumedService | 예 | 아니요 |
| ResourceGroup | 예 | 아니요 |
| ResourceURI | 예 | 예 |
| ChargeType | 예 | 예 |
| 단가 | 예 | 예 |
| 수량 | 예 | 예 |
| UnitType | 예 | 아니요 |
| BillingPreTaxTotal | 예 | 예 |
| BillingCurrency | 예 | 예 |
| PricingPreTaxTotal | 예 | 예 |
| PricingCurrency | 예 | 예 |
| ServiceInfo1 | 예 | 아니요 |
| ServiceInfo2 | 예 | 아니요 |
| 태그 | 예 | 아니요 |
| AdditionalInfo | 예 | 아니요 |
| EffectiveUnitPrice | 예 | 예 |
| PCToBCExchangeRate | 예 | 예 |
| EntitlementId | 예 | 예 |
| EntitlementDescription | 예 | 아니요 |
| PartnerEarnedCreditPercentage | 예 | 아니요 |
| CreditPercentage | 예 | 예 |
| CreditType | 예 | 예 |
| BenefitOrderID | 예 | 예 |
| BenefitID | 예 | 아니요 |
| BenefitType | 예 | 예 |
Important
v1에서 API v2로 이동할 때 이러한 변경 내용을 기록해 둡다.
각 특성의 이름은 대문자로 시작합니다.
unitOfMeasure 가 이제 Unit입니다. 특성의 의미와 값은 동일합니다.
resellerMpnId 는 이제 Tier2MpnId입니다. 특성의 의미와 값은 동일합니다.
rateOfPartnerEarnedCredit의 이름과 값이 PartnerEarnedCreditPercentage로 변경되었습니다. 특성의 새 이름과 값은 분수 대신 백분율을 반영합니다. 예를 들어 0.15는 이제 15입니다.
rateOfCredit 은 이제 CreditPercentage입니다. 특성의 의미와 값이 변경되었습니다. 예를 들어 1.00은 이제 100입니다.
샘플 코드
자세한 내용은 파트너 센터 API 샘플: 청구 조정 데이터 가져오기를 참조하세요.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기