Api rekonsiliasi penggunaan harian yang ditagih dan tidak ditagih
Berlaku untuk: Pusat Mitra (tidak tersedia di Azure Government, Azure Jerman, atau Azure Tiongkok 21Vianet.)
API asinkron kami menawarkan cara yang lebih cepat dan lebih mudah dikelola untuk mengakses data penagihan dan rekonsiliasi melalui blob Azure. Dengan API ini, Anda tidak perlu membuka koneksi selama berjam-jam atau mengulangi batch 2.000 item baris.
Kami mengoptimalkan API rekonsiliasi penggunaan harian perdagangan baru kami menggunakan kunci valet dan pola balasan permintaan asinkron. Saat Anda menggunakan API ini, Anda menerima token yang dapat Anda gunakan untuk mengakses semua atribut atau subset data rekonsiliasi penggunaan harian yang dinilai.
Catatan
API baru tidak dihosting di host API Pusat Mitra. Sebagai gantinya, Anda dapat menemukannya di MS Graph di Menggunakan Microsoft Graph API untuk mengekspor data tagihan mitra - Microsoft Graph v1.0 | Microsoft Learn. Untuk mengakses API ini, lihat detail berikut.
Anda hanya dapat menggunakan API ini untuk cloud publik/global MS Graph. Mereka belum tersedia untuk Azure Government, Azure Jerman, atau Azure Tiongkok 21Vianet.
Catatan
Jika Anda telah menggunakan versi beta kami, Anda mungkin tidak melihat perubahan signifikan dalam versi yang tersedia secara umum (GA). Sebaiknya bandingkan dua versi untuk memahami perbedaan dan pembaruan.
Penting
Penggunaan peringkat harian perdagangan baru tidak termasuk biaya untuk produk-produk ini:
- Reservasi Azure
- Paket penghematan Azure
- Office
- Dynamics
- Microsoft Power Apps
- Perangkat lunak abadi
- Langganan perangkat lunak
- Produk SaaS non-Microsoft
Ringkasan API
Untuk mengambil item baris penggunaan harian perdagangan baru secara asinkron, gunakan dua titik akhir API. Berikut prosesnya:
Titik akhir item baris penggunaan
Gunakan API ini untuk mengambil item baris penggunaan harian yang ditagih atau tidak ditagih. Anda mendapatkan status HTTP 202 dan URL di header lokasi. Polling URL ini secara berkala hingga Anda menerima status sukses dengan URL manifes.
Titik akhir status operasi
Untuk mendapatkan status sukses, terus panggil API ini secara berkala. Jika data belum siap, respons API menyertakan header Coba Lagi-Setelah untuk memberi tahu Anda berapa lama menunggu sebelum mencoba lagi. Setelah operasi selesai, Anda mendapatkan sumber daya manifes dengan folder penyimpanan tempat Anda dapat mengunduh data penggunaan. Respons memecah file menjadi bagian yang lebih kecil untuk throughput dan paralelisme I/O yang dioptimalkan.
Diagram urutan
Berikut adalah diagram urutan yang memperlihatkan langkah-langkah untuk mengunduh data rekonsiliasi.
Urutan tindakan pengguna
Untuk mengambil item baris rekonsiliasi penggunaan harian perdagangan baru, ikuti langkah-langkah berikut:
Langkah 1: Kirim permintaan
Kirim permintaan POST ke titik akhir API.
Dapatkan item baris penggunaan harian yang tidak ditagih
Dapatkan item baris penggunaan harian perdagangan baru yang tidak ditagih untuk bulan kalender atau periode penagihan saat ini atau terakhir.
Permintaan 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"
}
Isi permintaan
| Atribut | Wajib | Tipe | Deskripsi |
|---|---|---|---|
| attributeSet | Salah | String | Pilih "penuh" untuk semua atribut atau "dasar" untuk set terbatas. Nilai defaultnya adalah "penuh." (Lihat daftar atribut di sini). Opsional. |
| billingPeriod | Benar | String | Gunakan "saat ini" atau "terakhir" (sama seperti "sebelumnya" di API V1) untuk mendapatkan penggunaan berperingkat harian untuk bulan kalender atau periode penagihan saat ini atau terakhir. Harus diisi. |
| currencyCode | Benar | String | Kode mata uang penagihan mitra. Harus diisi. |
Header permintaan
Untuk meminta header api, lihat Keandalan dan dukungan.
Respons API
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Saat Anda menggunakan API, biasanya mengembalikan status HTTP 202. Untuk melihat kemungkinan status lain berdasarkan permintaan Anda, lihat Status respons API Standar.
| Kode | Deskripsi |
|---|---|
| 202 – Diterima | Permintaan Anda diterima. Untuk memeriksa status permintaan Anda, kueri URL yang disediakan di header lokasi. |
Dapatkan item baris penggunaan berperingkat harian yang ditagih
Dapatkan item baris penggunaan berperingkat harian yang ditagih perdagangan baru untuk faktur untuk periode penagihan tertutup.
Permintaan API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Parameter kueri
T/A
Isi permintaan
| Atribut | Wajib | Tipe | Deskripsi |
|---|---|---|---|
| invoiceId | Benar | String | Pengidentifikasi unik untuk setiap faktur. Harus diisi. |
| attributeSet | Salah | String | Pilih "penuh" untuk semua atribut atau "dasar" untuk set terbatas. Nilai defaultnya adalah "penuh." (Lihat daftar atribut di sini). Opsional. |
Header permintaan
Meminta header untuk API. Untuk mempelajari lebih lanjut, lihat keandalan dan dukungan.
Respons API
HTTP/1.1 202 Diterima
Lokasi: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
Saat Anda menggunakan API, biasanya mengembalikan status HTTP 202. Untuk kemungkinan status lain berdasarkan permintaan Anda, lihat Status.
| Kode | Deskripsi |
|---|---|
| 202 – Diterima | Permintaan Anda diterima. Untuk memeriksa status permintaan Anda, kueri URL yang disediakan di header lokasi. |
Langkah 2: Periksa status permintaan
Untuk memeriksa status permintaan, tunggu respons HTTP 200 dengan status "berhasil" atau "gagal." Jika permintaan berhasil, URL manifes disediakan di atribut "resourceLocation".
Dapatkan status Operasi
Mengambil status permintaan.
Permintaan API
Parameter permintaan
| Nama | Sertakan dalam | Wajib | Tipe | Deskripsi |
|---|---|---|---|---|
| operationId | URI Permintaan | Benar | String | ID unik untuk memeriksa status permintaan. Harus diisi. |
Header permintaan
Untuk meminta header api, lihat Keandalan dan dukungan.
Isi permintaan
T/A.
Status Respons
Selain status HTTP standar, API dapat mengembalikan status HTTP berikut:
| Kode | Deskripsi |
|---|---|
| 410 – Hilang | Tautan manifes hanya aktif untuk durasi tertentu yang ditetapkan oleh server. Setelah waktu ini berlalu, Anda harus mengirimkan permintaan baru untuk mengakses manifes. |
Payload respons
Payload respons API mencakup atribut berikut:
| Atribut | Wajib | Deskripsi |
|---|---|---|
| id | Benar | ID unik untuk setiap respons. Harus diisi. |
| status | Benar | Nilai dan tindakan (diperlukan): notstarted: Tunggu waktu yang ditentukan di header "Coba Lagi-Setelah", lalu lakukan panggilan lain untuk memeriksa status. berjalan: Tunggu waktu yang ditentukan di header "Coba Lagi-Setelah", lalu lakukan panggilan lain untuk memeriksa status. berhasil: Data siap. Ambil payload manifes menggunakan URI yang ditentukan dalam resourceLocation. gagal: Operasi gagal secara permanen. Hidupkan ulang. |
| createdDateTime | Benar | Waktu ketika permintaan dibuat. Harus diisi. |
| lastActionDateTime | Benar | Waktu status terakhir diubah. Harus diisi. |
| resourceLocation | Salah | URI untuk payload manifes. Opsional. |
| kesalahan | Salah | Jika operasi gagal, detail kesalahan disediakan dalam format JSON. Opsional. Atribut berikut mungkin disertakan: message (Required): Deskripsi terperinci tentang kesalahan. code (Wajib): Jenis kesalahan yang terjadi. |
Objek lokasi sumber daya
| Atribut | Deskripsi |
|---|---|
| id | Pengidentifikasi unik untuk manifes. |
| schemaVersion | Versi skema manifes. |
| dataFormat | Format file data penagihan. compressedJSON: format data di mana setiap blob adalah file terkompresi yang berisi data dalam format baris JSON . Untuk mengambil data dari setiap blob, dekompresi. |
| createdDateTime | Tanggal dan waktu ketika file manifes dibuat. |
| eTag | Versi data manifes. Perubahan informasi penagihan menghasilkan nilai baru. |
| partnerTenantId | ID penyewa mitra. |
| rootDirectory | Direktori akar file. |
| sasToken | Token SAS (tanda tangan akses bersama) yang memungkinkan Anda membaca semua file di bawah direktori. |
| partitionType | Membagi data menjadi beberapa blob berdasarkan atribut "partitionValue" . Sistem membagi partisi yang melebihi angka yang didukung. Secara default, data dipartisi berdasarkan jumlah item baris dalam file. Jangan tetapkan jumlah item baris atau ukuran file dalam kode, karena nilai-nilai ini mungkin berubah. |
| blobCount | Jumlah total file untuk ID penyewa mitra ini. |
| blob | Array JSON objek "blob" yang berisi detail file untuk ID penyewa mitra. |
| objek blob | Objek yang berisi detail berikut: |
| nama | Nama blob. |
| partitionValue | Partisi yang berisi file. Partisi besar dibagi menjadi beberapa file, dengan setiap file berisi "partitionValue" yang sama. |
Permintaan API
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Respons API
Respons merekomendasikan menunggu selama 10 detik sebelum mencoba lagi saat memproses data.
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"
}
Permintaan API
(10 detik setelah permintaan sebelumnya...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
Respons API
API mengembalikan status "berhasil" dan URI untuk "resourceLocation."
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"
}
\]
}
}
Langkah 3: Unduh item baris rekonsiliasi penggunaan harian dari penyimpanan blob Azure
Dapatkan token tanda tangan akses bersama (SAS) dan lokasi penyimpanan blob dari properti "sasToken" dan "rootDirectory" respons API payload manifes. Gunakan Azure Storage SDK/tool untuk mengunduh dan membuka zip file blob. Ini dalam format JSONLines .
Tip
Lihat kode sampel kami untuk mengunduh dan membuka zip file blob Azure ke database lokal Anda.
Status respons API standar
Anda mungkin menerima status HTTP ini dari respons API:
| Kode | Keterangan |
|---|---|
| 400 – Permintaan Buruk | Permintaan hilang atau berisi data yang salah. Periksa isi respons untuk detail kesalahan. |
| 401 – Tidak sah | Pemanggil tidak diautentikasi, dan Anda harus mengautentikasi dengan layanan API mitra sebelum melakukan panggilan pertama. |
| 403 – Terlarang | Anda tidak memiliki otorisasi yang diperlukan untuk membuat permintaan. |
| 404 – Tidak Ditemukan | Sumber daya yang diminta tidak tersedia dengan parameter input yang disediakan. |
| 410 – Hilang | Tautan manifes kehabisan waktu atau kedaluwarsa. Kirim permintaan baru. |
| 500 – Kesalahan Server Internal | API atau salah satu dependensinya tidak dapat memenuhi permintaan saat ini. Coba lagi nanti. |
| 5000 – Tidak ada data yang tersedia | Sistem tidak memiliki data untuk parameter input yang disediakan. |
Membandingkan versi beta dan GA
Lihat tabel perbandingan untuk memahami perbedaan antara versi beta dan yang tersedia secara umum (GA). Jika Anda menggunakan versi beta, beralih ke versi GA harus mudah.
| Informasi penting | Beta | Tersedia secara umum |
|---|---|---|
| Titik akhir host API | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| Metode HTTP | POST | POST |
| Titik akhir API penggunaan harian yang tidak ditagih | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Parameter input untuk API penggunaan harian yang tidak ditagih | Untuk menentukan parameter dalam permintaan API, sertakan dalam string kueri URL permintaan. Misalnya, untuk menentukan parameter periode dan currencyCode, tambahkan ?period=current¤cyCode=usd ke URL permintaan. |
Untuk memberikan input, sertakan objek JSON dalam isi permintaan. Objek JSON harus berisi properti berikut: * currencyCode: Kode mata uang untuk faktur. Misalnya, USD. * billingPeriod: Periode penagihan untuk faktur. Misalnya, saat ini. Berikut adalah contoh objek JSON yang menyertakan properti currencyCode dan billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Titik akhir API penggunaan berperingkat harian yang ditagih | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Parameter input untuk API penggunaan berperingkat harian yang ditagih | Untuk menentukan parameter dalam permintaan API, sertakan invoiceId dalam URL permintaan. Selain itu, Anda dapat menyertakan parameter fragmen opsional dalam string kueri untuk mengambil set atribut lengkap. Misalnya, untuk mengambil sekumpulan atribut lengkap, tambahkan ?fragment=full ke URL permintaan. |
Untuk memberikan input, sertakan objek JSON dalam isi permintaan. Objek JSON harus berisi properti berikut: * invoiceId: ID faktur. Misalnya, G00012345. * attributeSet: Kumpulan atribut yang akan disertakan dalam respons. Misalnya, penuh. Berikut adalah contoh objek JSON yang menyertakan properti invoiceId dan attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Sumber daya manifes | Gunakan metode GET /manifests/{id} terpisah untuk mengambil sumber daya manifes. | Gunakan metode GET /operations/{Id}, yang mengembalikan sumber daya manifes terkait dalam resourceLocation yang menghilangkan kebutuhan akan panggilan terpisah ke metode GET /manifests/{id}. |
| Perubahan pada skema manifes | ||
| "id": Tidak tersedia | "id": Pengidentifikasi unik untuk sumber daya manifes. | |
| "version": Available | "version": berganti nama menjadi "schemaversion." | |
| "dataFormat": Tersedia | "dataFormat": Tersedia. | |
| "utcCretedDateTime": Tersedia | "utcCretedDateTime": diganti namanya menjadi "createdDateTime." | |
| "eTag": Tersedia | "eTag": Tersedia. | |
| "partnerTenantId": Tersedia | "partnerTenantId": Tersedia | |
| "rootFolder": Tersedia | "rootFolder": diganti namanya menjadi "rootDirectory." | |
| "rootFolderSAS": Tersedia | "rootFolderSAS": diganti namanya menjadi "sasToken." Sekarang menyediakan token dan tidak lagi menyertakan jalur direktori akar. Untuk mengakses direktori, gunakan properti "rootDirectory". | |
| "partitionType": Tersedia | "partitionType": Tersedia. | |
| "blobCount": Tersedia | "blobCount": Tersedia. | |
| "sizeInBytes": Tersedia | "sizeInBytes": Tidak tersedia. | |
| "blob": Tersedia | "blob": Tersedia. | |
| "objek blob": Tersedia | "objek blob": Tersedia. | |
| "name": Available | "name": Tersedia. | |
| "partitionValue": Tersedia | "partitionValue": Tersedia. |
Atribut item baris rekonsiliasi penggunaan harian
Untuk membandingkan atribut yang dikembalikan oleh API rekonsiliasi penggunaan berperingkat harian untuk set atribut "penuh" atau "dasar", lihat informasi berikut.
| Atribut | Penuh | Dasar |
|---|---|---|
| PartnerId | yes | yes |
| PartnerName | yes | yes |
| ID Pelanggan | yes | yes |
| CustomerName | yes | Ya |
| CustomerDomainName | yes | no |
| CustomerCountry | yes | no |
| MpnId | yes | no |
| Tier2MpnId | yes | no |
| InvoiceNumber | yes | yes |
| ProductId | yes | yes |
| SkuId | yes | yes |
| AvailabilityId | yes | no |
| SkuName | yes | yes |
| ProductName | yes | no |
| PublisherName | yes | yes |
| PublisherId | yes | no |
| SubscriptionDescription | yes | no |
| SubscriptionId | yes | yes |
| ChargeStartDate | yes | yes |
| ChargeEndDate | yes | yes |
| UsageDate | yes | yes |
| MeterType | yes | no |
| MeterCategory | yes | no |
| MeterId | yes | no |
| MeterSubCategory | yes | no |
| MeterName | yes | no |
| MeterRegion | yes | no |
| Unit | yes | yes |
| ResourceLocation | yes | no |
| ConsumedService | yes | no |
| ResourceGroup | yes | no |
| ResourceURI | yes | yes |
| chargeType | yes | yes |
| UnitPrice | yes | yes |
| Quantity | yes | yes |
| UnitType | yes | no |
| BillingPreTaxTotal | yes | yes |
| billingCurrency | yes | yes |
| PricingPreTaxTotal | yes | yes |
| PricingCurrency | yes | yes |
| ServiceInfo1 | yes | no |
| ServiceInfo2 | yes | no |
| Tag | yes | no |
| AdditionalInfo | yes | no |
| EffectiveUnitPrice | yes | yes |
| PCToBCExchangeRate | yes | yes |
| EntitlementId | yes | yes |
| EntitlementDescription | yes | no |
| PartnerEarnedCreditPercentage | yes | no |
| CreditPercentage | yes | yes |
| CreditType | yes | yes |
| BenefitOrderID | yes | yes |
| BenefitID | yes | no |
| BenefitType | yes | yes |
Penting
Catat perubahan ini saat pindah ke API v2 dari v1.
Setiap nama atribut dimulai dalam huruf besar.
unitOfMeasure sekarang menjadi Unit. Arti dan nilai atribut sama.
resellerMpnId sekarang menjadi Tier2MpnId. Arti dan nilai atribut sama.
Nama dan nilai rateOfPartnerEarnedCredit telah berubah menjadi PartnerEarnedCreditPercentage. Nama dan nilai baru atribut mencerminkan persentase alih-alih pecahan. Misalnya, 0,15 sekarang menjadi 15.
rateOfCredit sekarang adalah CreditPercentage. Arti dan nilai atribut telah berubah. Misalnya, 1.00 sekarang menjadi 100.
Kode Sampel
Untuk mempelajari selengkapnya, lihat Sampel API Pusat Mitra: Mendapatkan data pengintaian penagihan.
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk