청구된 청구서 조정 API v2(GA)
적용 대상: 파트너 센터(소버린 클라우드에서 사용할 수 없음)
비동기 API는 Azure Blob을 통해 청구 및 조정 데이터에 액세스하는 더 빠르고 관리하기 쉬운 방법을 제공합니다. 이 API를 사용하면 연결을 몇 시간 동안 열어 두거나 한 번에 2,000개의 품목 일괄 처리를 반복할 필요가 없습니다.
발레 키 및 비동기 요청-회신 패턴을 사용하여 청구된 청구서 조정 API를 최적화했습니다. 이 API는 청구된 청구서 조정 데이터의 모든 특성 또는 하위 집합에 액세스하는 데 사용할 수 있는 SAS(공유 액세스 서명) 토큰을 제공합니다.
참고 항목
새 API는 파트너 센터 API 호스트에서 호스트되지 않습니다. 대신 Microsoft Graph API를 사용하여 파트너 청구 데이터인 Microsoft Graph v1.0을 내보낼 때 MS Graph에서 찾을 수 있습니다. 이 API에 액세스하려면 다음 세부 정보를 참조하세요.
이제 MS Graph 퍼블릭/글로벌 클라우드에 대해서만 이 API를 사용할 수 있습니다. Azure Government, Azure 독일 또는 Azure 중국 21Vianet에서는 아직 사용할 수 없습니다.
API 개요
청구된 청구서 조정 데이터를 비동기적으로 검색하려면 두 개의 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/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
쿼리 매개 변수
해당 없음
요청 본문
| 특성 | 필수 | Type | 설명 |
|---|---|---|---|
| attributeSet | False | 문자열 | 모든 특성에 대해 "full"을 선택하거나 제한된 집합에 대해 "기본"을 선택합니다. 기본값은 "full"입니다. (이 문서의 특성 목록을 참조하세요). 선택 사항. |
| invoiceId | True | 문자열 | 각 청구서에 대한 고유 식별자입니다. 필수입니다. |
요청 헤더
Microsoft Graph 사용에 대한 모범 사례에 나열된 단계를 사용하여 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을 쿼리합니다. |
2단계: 요청 상태 확인
요청의 상태 검사 "성공" 또는 "실패"상태 있는 HTTP 200 응답을 기다립니다. 요청이 성공하면 "resourceLocation" 특성에서 매니페스트 URL을 가져옵니다.
작업 상태 가져오기
요청의 상태 검색합니다.
API 요청
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
요청 매개 변수
| 속성 | 다음 포함 | 필수 | Type | 설명 |
|---|---|---|---|---|
| operationId | 요청 URI | True | 문자열 | 요청 상태 검사 고유 ID입니다. 필수입니다. |
요청 헤더
Microsoft Graph 사용에 대한 모범 사례에 나열된 단계를 사용하여 API에 대한 헤더를 요청합니다.
요청 본문
해당 없음.
응답 상태
이 문서의 표준 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 형식으로 제공됩니다. 선택 사항. 다음 특성이 포함됩니다. 메시지: 오류에 대한 자세한 설명입니다. code: 발생한 오류의 유형입니다. |
리소스 위치 개체
| 특성 | 설명 |
|---|---|
| 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"가 포함됩니다. |
| 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 응답이 속성됩니다. Blob 파일을 다운로드하고 압축을 풉니다. JSONLines 형식입니다.
표준 API 응답 상태
API의 응답에서 다음 HTTP 상태 가져올 수 있습니다.
| 코드 | 설명 |
|---|---|
| 400 - 잘못된 요청 | 요청이 없거나 잘못된 데이터가 포함되어 있습니다. 오류 세부 정보는 응답 본문을 확인합니다. |
| 401 - 권한 없음 | 호출자는 인증되지 않으며, 첫 번째 호출을 하기 전에 파트너 API 서비스로 인증해야 합니다. |
| 403 - 사용 권한 없음 | 요청을 만드는 데 필요한 권한 부여가 없습니다. |
| 404 – 찾을 수 없음 | 요청된 리소스는 제공된 입력 매개 변수와 함께 사용할 수 없습니다. |
| 410 – 사라지다 | 매니페스트 링크가 더 이상 유효하지 않거나 활성 상태가 아닙니다. 새 요청을 제출합니다. |
| 500 – 내부 서버 오류 | API 또는 해당 종속성 중 하나가 지금 요청을 수행할 수 없습니다. 나중에 다시 시도하세요. |
청구된 청구서 조정 데이터 특성
"전체" 또는 "기본" 특성 집합에 대해 청구된 청구서 조정 API에서 반환된 특성을 비교하려면 다음 표를 참조하세요.
| 특성 | 전체 | Basic |
|---|---|---|
| PartnerId | 예 | 예 |
| 고객 ID | 예 | 예 |
| CustomerName | 예 | 예 |
| CustomerDo기본Name | 예 | 아니요 |
| CustomerCountry | 예 | 아니요 |
| InvoiceNumber | 예 | 예 |
| MpnId | 예 | 아니요 |
| Tier2MpnId | 예 | 예 |
| OrderId | 예 | 예 |
| OrderDate | 예 | 예 |
| ProductId | 예 | 예 |
| SkuId | 예 | 예 |
| AvailabilityId | 예 | 예 |
| SkuName | 예 | 아니요 |
| ProductName | 예 | 예 |
| ChargeType | 예 | 예 |
| 단가 | 예 | 예 |
| 수량 | 예 | 아니요 |
| 소계 | 예 | 예 |
| TaxTotal | 예 | 예 |
| 총계 | 예 | 예 |
| 통화 | 예 | 예 |
| PriceAdjustmentDescription | 예 | 예 |
| PublisherName | 예 | 예 |
| PublisherId | 예 | 아니요 |
| SubscriptionDescription | 예 | 아니요 |
| SubscriptionId | 예 | 예 |
| ChargeStartDate | 예 | 예 |
| ChargeEndDate | 예 | 예 |
| TermAndBillingCycle | 예 | 예 |
| EffectiveUnitPrice | 예 | 예 |
| UnitType | 예 | 아니요 |
| AlternateId | 예 | 아니요 |
| BillableQuantity | 예 | 예 |
| BillingFrequency | 예 | 아니요 |
| PricingCurrency | 예 | 예 |
| PCToBCExchangeRate | 예 | 예 |
| PCToBCExchangeRateDate | 예 | 아니요 |
| MeterDescription | 예 | 아니요 |
| ReservationOrderId | 예 | 예 |
| CreditReasonCode | 예 | 예 |
| SubscriptionStartDate | 예 | 예 |
| SubscriptionEndDate | 예 | 예 |
| 참조 | 예 | 예 |
| ProductQualifiers | 예 | 아니요 |
| PromotionId | 예 | 예 |
| ProductCategory | 예 | 예 |
샘플 코드
API 사용에 대한 지침은 C#의 샘플 코드를 포함하는 다음 링크를 참조하세요.
파트너 센터-청구-재연결 샘플: 파트너 센터(github.com)에서 청구 정찰 데이터를 가져오기 위한 API 샘플입니다.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기