청구서 발행 및 조정 API v2(베타)
적용 대상: 파트너 센터 | 21Vianet에서 운영되는 파트너 센터 | Microsoft Cloud for US Government 파트너 센터
이러한 API를 사용하여 청구 및 청구되지 않은 일일 등급 사용량 현황 데이터를 비동기적으로 가져옵니다.
참고 항목
청구된 일일 등급 사용량에 대한 이 API는 2024년 6월 30일 이후에 작동이 중지됩니다. 사용할 버전과 시기를 결정하려면 다음 세부 정보를 참조하세요.
- v2 GA로 전환하지 않는 한 2024년 6월 30일까지 이 API를 사용하여 2022년 9월부터 2024년 6월까지 청구 기간 동안 생성된 청구서에 대한 일일 등급 사용량 품목을 청구합니다.
- 2024년 6월 30일 이후에는 API v2 GA만 사용하여 2022년 9월부터 청구 기간 동안 생성된 청구서에 대해 청구되는 일일 등급 사용량 품목을 가져옵니다.
청구되지 않은 일일 등급 사용량에 대한 이 API는 2024년 6월 30일 이후에 작동이 중지됩니다. 사용할 버전과 시기를 결정하려면 다음 세부 정보를 참조하세요.
- v2 GA로 전환하지 않는 한 2024 년 6월 30일까지 이 API를 사용하여 현재 및 이전 청구 기간에 대한 청구되지 않은 일일 등급 사용량 품목을 가져옵니다.
- 2024년 6월 30일 이후 API v2 GA만 사용하여 현재 및 이전 청구에 대해 청구되지 않은 일일 정격 사용량 품목을 가져옵니다.
새 v2 GA API로 마이그레이션 준비를 시작하려면 다음 링크를 참조하세요.
참고 항목
API 또는 파트너 센터 포털을 통해 매일 청구되지 않은 사용량 현황 데이터를 검색할 수 있습니다. 데이터를 사용할 수 있게 되는 데 최대 24시간이 걸릴 수 있습니다. 그러나 위치 및 미터가 사용량을 보고하는 시기에 따라 추가 지연이 있을 수 있습니다.
경우에 따라 이전 달의 청구된 사용량 현황 데이터가 배달될 때까지 가장 최근의 청구되지 않은 사용량 현황 데이터가 표시되지 않을 수 있습니다. 이는 청구된 사용량 현황 데이터가 합의된 시간 내에 전달되도록 하기 위해 수행됩니다. 청구된 사용량 현황 데이터를 받으면 월 시작부터 업데이트된 모든 청구되지 않은 사용 현황 데이터를 검색할 수 있습니다.
Important
일일 등급 사용량 데이터에는 다음 제품에 대한 요금이 포함되지 않습니다.
- Azure 예약
- Azure 절약 플랜
- Office
- Dynamics
- Microsoft Power Apps
- 영구 소프트웨어
- 소프트웨어 구독
- 타사 SaaS 제품
API 개요
비동기 API는 관리 가능한 청크에서 청구 및 조정 데이터에 빠르게 액세스하는 새로운 방법입니다. 기본 시간 동안 열린 연결을 획득하고 수백만 개의 트랜잭션을 반복적으로 반복할 필요가 없습니다.
Microsoft는 청구 및 조정 API가 결과를 비동기적으로 제공하도록 최적화하기 위해 발레 키 및 비동기 요청-회신 패턴을 사용했습니다. API 응답은 모든 특성 또는 하위 집합을 사용하여 조정 데이터에 액세스하는 토큰을 제공합니다.
세 가지 새로운 단계(API 엔드포인트)를 사용하여 사용량 현황 데이터를 비동기적으로 다운로드할 수 있습니다. 자세한 내용은 다음을 참조하세요.
사용량 줄 항목 엔드포인트
이 API를 사용하여 청구되거나 청구되지 않은 소비 품목에 액세스합니다. 202 HTTP 상태 및 URL이 있는 위치 헤더를 반환합니다. 이 헤더는 매니페스트 URL을 사용하여 성공 상태 받을 때까지 정기적으로 폴링해야 합니다.
엔드포인트 상태 작업
성공 상태 받을 때까지 이 API를 정기적으로 폴링합니다. 요청된 데이터를 사용할 수 없는 경우 API 응답에는 다른 요청을 보내기 전에 대기해야 하는 시간을 나타내는 Retry-After 헤더가 포함됩니다.
매니페스트 엔드포인트
이 엔드포인트는 실제 청구 데이터를 다운로드할 수 있는 스토리지 폴더를 제공합니다. 응답은 파일을 분할하거나 분할하여 처리량 및 I/O 병렬 처리를 최적화합니다.
시퀀스 다이어그램
아래 다이어그램은 조정 데이터를 다운로드하는 데 필요한 단계를 보여 줍니다.
사용자 작업 순서
아래 단계에 따라 조정 데이터를 검색합니다.
1단계: 요청 제출
API 엔드포인트에 POST 요청을 제출합니다.
청구되지 않은 사용 현황 품목 가져오기
현재 또는 지난 달의 청구되지 않은 사용 현황 품목을 가져옵니다.
API 요청
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
요청 매개 변수
| 이름 | In | Required | Type | 설명 |
|---|---|---|---|---|
| fragment | 쿼리 | False | 문자열 | 전체 응답에 대해 "전체"를 선택하거나 특성 하위 집합에 대해 "기본"을 선택합니다. 기본값은 "full"입니다. 이 문서의 특성 목록을 참조하세요. |
| 기간 | 쿼리 | True | 문자열 | "현재" 또는 "마지막"을 사용하여 현재 또는 지난 달의 사용량을 가져옵니다. "last" 값은 기존 V1 API의 "이전"과 동일합니다. |
| currencyCode | 쿼리 | True | 문자열 | 파트너 청구 통화 코드입니다. |
사용되지 않는 요청 매개 변수
최신 API 버전에는 다음 URI 매개 변수가 필요하지 않습니다.
| 이름 | 설명 |
|---|---|
| Provider | 해당 없음. (모든 Azure 플랜 사용량을 반환하며 기존 V1 API의 "일회성"과 동일합니다.) |
| hasPartnerEarnedCredit | 해당 없음. (PEC에 관계없이 모든 데이터를 반환합니다.) |
| 크기 | 해당 없음. |
| Offset | 해당 없음. |
| seekOperation | 해당 없음. |
요청 헤더
이 문서의 API 에 대한 요청 헤더 목록을 참조하세요.
요청 본문
해당 없음.
API 응답
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
API는 HTTP 상태 202를 반환합니다. 요청에 따라 API는 다른 표준 상태 반환할 수 있습니다.
| 이름 | 설명 |
|---|---|
| 202 수락됨 | 요청이 수락되었습니다. 요청 상태 대한 작업 위치 헤더 URL을 쿼리합니다. |
청구된 사용량 품목 가져오기
닫힌 청구 기간에 대한 청구 등급 사용량 품목을 가져옵니다.
API 요청
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
요청 매개 변수
| 이름 | In | Required | Type | 설명 |
|---|---|---|---|---|
| invoiceId | Path | True | 문자열 | 파트너 센터 청구서 번호입니다. |
| 조각 | 쿼리 | False | 문자열 | 전체 응답에 대해 "전체"를 선택하거나 특성 하위 집합에 대해 "기본"을 선택합니다. 기본값은 "full"입니다. 이 문서의 특성 목록을 참조하세요. |
사용되지 않는 요청 매개 변수
최신 API 버전에는 다음 URI 매개 변수가 필요하지 않습니다.
| 이름 | 설명 |
|---|---|
| Provider | 해당 없음. (모든 Azure 플랜 사용량을 반환하며 기존 V1 API의 "일회성"과 동일합니다.) |
| hasPartnerEarnedCredit | 해당 없음. (PEC에 관계없이 모든 데이터를 반환합니다.) |
| 크기 | 해당 없음. |
| Offset | 해당 없음. |
| seekOperation | 해당 없음. |
요청 헤더
이 문서의 API 에 대한 요청 헤더 목록을 참조하세요.
요청 본문
해당 없음.
API 응답
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
API는 "HTTP 202 수락됨"을 반환합니다. 요청에 따라 API는 다른 표준 상태 반환할 수 있습니다.
| 이름 | 설명 |
|---|---|
| 202 수락됨 | 요청이 수락되었습니다. 작업 위치 헤더 URL을 폴링하여 요청 상태 확인합니다. |
2단계: 요청 상태 확인
터미널 상태 성공하거나 실패한 HTTP 200을 기다립니다. 매니페스트 URL은 성공 상태 "resourceLocation"이 됩니다.
작업 상태 가져오기
조정 데이터 요청의 상태 가져옵니다.
API 요청
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
요청 매개 변수
| 이름 | In | Required | Type | 설명 |
|---|---|---|---|---|
| operationId | Path | True | 문자열 | 작업 ID입니다. |
요청 헤더
이 문서의 API 에 대한 요청 헤더 목록을 참조하세요.
요청 본문
해당 없음.
응답 상태
이 문서의 표준 HTTP 상태 외에도 API는 HTTP 상태 아래를 반환할 수 있습니다.
| 이름 | 설명 |
|---|---|
| 410 없음 | 각 작업 링크는 지정된 양의 서버 제어 시간 동안 활성화됩니다. 시간이 경과한 후 클라이언트는 새 요청을 제출해야 합니다. |
응답 페이로드
API 응답 페이로드는 다음 특성을 반환합니다.
| 속성 | 선택 사항 | 설명 |
|---|---|---|
| createdDateTime | false | 요청 시간입니다. |
| lastActionDateTime | false | 상태 변경 시간입니다. |
| resourceLocation | true | 매니페스트 페이로드 URI입니다. |
| status | false | 가능한 값 및 작업입니다. |
| 값 | 클라이언트 작업 |
|---|---|
| notstarted | "Retry-After" 헤더에 지정된 시간을 기다린 후 상태 검사 또 다른 호출을 합니다. |
| 실행 중 | "Retry-After" 헤더에 지정된 시간을 기다린 후 상태 검사 또 다른 호출을 합니다. |
| 성공 | 데이터가 준비되었음을 나타내는 최종 작업 상태입니다. resourceLocation에 지정된 URI를 사용하여 매니페스트 페이로드를 검색합니다. |
| 실패 | 영구적 오류를 나타내는 터미널 상태입니다. 작업을 다시 시작합니다. |
오류 특성의 경우:
| 속성 | 선택 사항 | 설명 |
|---|---|---|
| error | true | 작업 상태 실패한 경우 json 형식으로 제공되는 오류 세부 정보입니다. |
| 속성 | 선택 사항 | 설명 |
|---|---|---|
| message | false | 오류를 자세히 설명합니다. |
| 코드 | false | 발생한 오류의 종류를 나타냅니다. |
API 요청
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API 응답
응답은 데이터를 처리할 때 다시 시도하기 전에 10초 동안 대기하는 것을 제안합니다.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
API 요청
(이전 요청 후 10초)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API 응답
API는 "succeeded" 상태 및 "resourceLocation" URI를 반환합니다.
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
3단계: 매니페스트 페이로드 가져오기
호출자는 조정 데이터가 Azure Blob에 저장되는 위치에 대해 자세히 알아보기 위해 매니페스트 URL에 GET 요청을 합니다.
매니페스트 가져오기
조정 데이터의 Azure 스토리지 위치에 대한 정보가 있는 매니페스트를 검색합니다.
API 요청
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
요청 매개 변수
| 이름 | In | Required | Type | 설명 |
|---|---|---|---|---|
| manifestId | Path | True | 문자열 | 매니페스트 ID입니다. |
요청 헤더
이 문서의 [API에 대한 요청 헤더 목록]을 참조하세요.
요청 본문
해당 없음.
응답 상태
표준 HTTP 상태 외에도 API는 HTTP 상태 아래에 반환할 수 있습니다.
| 이름 | 설명 |
|---|---|
| 410 없음 | 각 매니페스트 링크는 지정된 양의 서버 제어 시간 동안 활성화됩니다. 시간이 경과한 후 클라이언트는 새 요청을 제출해야 합니다. |
응답 페이로드
API 응답은 다음 특성을 반환합니다.
| 이름 | 설명 |
|---|---|
| 버전 | 매니페스트 스키마 버전입니다. |
| dataFormat | 청구 데이터 파일 형식입니다. 가능한 값 compressedJSONLines: 각 Blob은 압축된 파일이며 파일의 데이터는 JSON 줄 형식입니다. 파일에 액세스하려면 파일의 압축을 해제합니다. |
| utcCreatedDateTime | 매니페스트 파일 생성 시간입니다. |
| eTag | 매니페스트 데이터 버전입니다. 청구 정보가 변경되어 새 eTag 값이 생성됩니다. |
| partnerTenantId | 파트너 테넌트 ID입니다. |
| rootFolder | 파일의 루트 디렉터리입니다. |
| rootFolderSAS | 파일에 액세스하기 위한 SAS 토큰입니다. |
| partitionType | 이 속성은 데이터를 나눕니다. 지정된 파티션에 지원되는 수보다 많은 수의 데이터가 "partitionValue"에 해당하는 여러 파일로 분할됩니다. 데이터는 기본적으로 파일의 줄 항목 수로 분할됩니다. 변경될 수 있으므로 코드에서 고정된 수의 줄 항목 또는 파일 크기를 설정하지 마세요. |
| blobCount | 이 파트너 테넌트 ID의 총 파일 수입니다. |
| sizeInBytes | 모든 파일의 총 바이트 수입니다. |
| blobs | 파트너 테넌트 ID에 대한 모든 파일의 세부 정보가 있는 "Blob" 개체의 JSON 배열입니다. |
| Blob 개체 | |
| 속성 | Blob의 이름입니다. |
| sizeInBytes | Blob 크기(바이트)입니다. |
| partitionValue | 파일이 포함된 파티션입니다. 큰 파티션은 각각 동일한 "partitionValue"를 가진 여러 파일로 분할됩니다. |
샘플 매니페스트 페이로드
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
4단계: 스토리지 위치에서 사용량 조정 데이터 다운로드
"rootFolderSAS" 및 "rootFolder"에서 SAS 토큰 및 Blob Storage 위치를 가져오면 매니페스트 페이로드 API 응답이 속성됩니다. Azure Storage SDK/도구를 사용하여 Blob 파일을 다운로드하고 압축을 풉니다. JSON 줄 형식입니다.
표준 API 요청 헤더
모든 API는 다음 헤더를 허용합니다.
| 이름 | Required | Type | 설명 |
|---|---|---|---|
| Authorization | True | 문자열 | 권한 부여 전달자 토큰입니다. |
| ms-correlationid | False | 문자열 | 내부 요청 추적기입니다. 각 요청은 새 추적기(GUID)를 생성합니다. |
| ms-cv | False | 문자열 | 내부 요청 추적기입니다. |
| ms-requestid | False | 문자열 | 요청 idempotency ID입니다. |
표준 API 응답 상태
다음은 API 응답의 HTTP 상태입니다.
| 이름 | 설명 |
|---|---|
| 400 잘못된 요청 | 누락되거나 잘못된 데이터가 있습니다. 오류 세부 정보는 응답 본문에 포함됩니다. |
| 401 권한 없음 | 호출자는 인증되지 않으며 첫 번째 호출을 하기 전에 파트너 API 서비스를 사용하여 인증해야 합니다. |
| 403 금지 | 호출자에게 요청을 할 권한이 없습니다. |
| 500 내부 서버 오류 | API 또는 해당 종속성 중 하나가 요청을 처리할 수 없습니다. 나중에 다시 시도하세요. |
| 404 찾을 수 없음 | 입력 매개 변수와 함께 리소스를 사용할 수 없습니다. |
| 410 없음 | 매니페스트 링크의 시간이 초과되거나 경과되었습니다. 새 요청을 제출합니다. |
사용량 현황 데이터 특성
"full" 또는 "basic" 요청 매개 변수가 있는 청구되거나 청구되지 않은 사용량 API 응답은 다음 특성을 반환합니다.
| Attribute | "full" | "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 | 예 | 예 |
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기