Faturalandırılmış ve faturalanmamış günlük derecelendirilmiş kullanım mutabakatı API'si v2 (GA)
Şunlar için geçerlidir: İş Ortağı Merkezi (Azure Kamu, Azure Almanya veya Azure China 21Vianet'te kullanılamaz.)
Zaman uyumsuz API'lerimiz, Azure blobları aracılığıyla faturalama ve mutabakat verilerine erişmek için daha hızlı ve daha yönetilebilir bir yol sunar. Bu API'lerle bağlantıyı saatlerce açık tutmanız veya 2.000 satırlık öğelerden oluşan toplu işlemler arasında döngü yapmanız gerekmez.
Vale anahtarı ve zaman uyumsuz istek-yanıt desenlerini kullanarak yeni ticaret günlük derecelendirilmiş kullanım mutabakat API'lerimizi iyileştirdik. Bu API'leri kullandığınızda, tüm özniteliklere veya günlük derecelendirilmiş kullanım mutabakat verilerinin bir alt kümesine erişmek için kullanabileceğiniz bir belirteç alırsınız.
Not
Yeni API'ler İş Ortağı Merkezi API ana bilgisayarında barındırılamaz. Bunun yerine bunları MS Graph'ta bulabilirsiniz: İş ortağı faturalama verilerini dışarı aktarmak için Microsoft Graph API'sini kullanma - Microsoft Graph v1.0 | Microsoft Learn. Bu API'lere erişmek için aşağıdaki ayrıntılara bakın.
Bu API'leri yalnızca MS Graph genel/genel bulutu için kullanabilirsiniz. Bunlar henüz Azure Kamu, Azure Almanya veya Azure China 21Vianet için kullanılamaz.
Not
Beta sürümümüzü kullandıysanız genel kullanıma sunulan (GA) sürümde önemli değişiklikler fark etmeyebilirsiniz. Farklılıkları ve güncelleştirmeleri anlamak için iki sürümü karşılaştırmanızı öneririz.
Önemli
Yeni ticaret günlük derecelendirmeli kullanım, bu ürünlerin ücretlerini içermez:
- Azure rezervasyonu
- Azure tasarruf planı
- Office
- Dynamics
- Microsoft Power Apps
- Kalıcı yazılım
- Yazılım aboneliği
- Microsoft dışı SaaS ürünü
API’ye genel bakış
Yeni ticaret günlük derecelendirilmiş kullanım satırı öğelerini zaman uyumsuz olarak almak için iki API uç noktası kullanın. Süreç şu şekildedir:
Kullanım satır öğesi uç noktası
Faturalanmış veya faturalanmamış günlük derecelendirilmiş kullanım satırı öğelerini almak için bu API'yi kullanın. Konum üst bilgisinde 202 HTTP durumunu ve URL'yi alırsınız. Bildirim URL'si ile bir başarı durumu elde edene kadar düzenli aralıklarla bu URL'yi yokla.
İşlem durumu uç noktası
Başarı durumunu almak için bu API'yi düzenli aralıklarla çağırmaya devam edin. Veriler hazır değilse API yanıtı, yeniden denemeden önce ne kadar beklemeniz gerektiğini gösteren bir Yeniden Deneme-Sonra üst bilgisi içerir. İşlem tamamlandığında, kullanım verilerini indirebileceğiniz depolama klasörüne sahip bir bildirim kaynağı alırsınız. Yanıt, iyileştirilmiş aktarım hızı ve G/Ç paralelliği için dosyaları daha küçük parçalara ayırır.
Sıralı diyagram
Mutabakat verilerini indirme adımlarını gösteren bir sıralı diyagram aşağıdadır.
Kullanıcı eylem dizisi
Yeni ticaret günlük derecelendirilmiş kullanım mutabakatı satırı öğelerini almak için şu adımları izleyin:
1. Adım: İstek gönderme
API uç noktasına bir POST isteği gönderin.
Faturalanmamış günlük derecelendirilmiş kullanım satırı öğelerini alma
Geçerli veya son takvim ayı veya faturalama dönemi için yeni ticari faturalanmamış günlük derecelendirilmiş kullanım satırı öğeleri alın.
API isteği
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"
}
Request body
İstek üst bilgileri
API için üst bilgi istemek için bkz . Güvenilirlik ve destek.
API yanıtı
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
API'yi kullandığınızda genellikle bir HTTP 202 durumu döndürür. İsteklerinize göre diğer olası durumları görmek için bkz . Standart API yanıt durumları.
| Kod | Description |
|---|---|
| 202 – Kabul Edildi | İsteğiniz kabul edildi. İsteğinizin durumunu denetlemek için konum üst bilgisinde sağlanan URL'yi sorgula. |
Faturalanan günlük derecelendirilmiş kullanım satırı öğelerini alma
Kapatılan faturalama dönemine ait bir fatura için yeni ticaret faturalanmış günlük derecelendirmeli kullanım satırı öğelerini alın.
API isteği
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Sorgu parametreleri
Yok
Request body
İstek üst bilgisi
API için istek üst bilgileri. Daha fazla bilgi edinmek için güvenilirlik ve destek konularına bakın.
API yanıtı
HTTP/1.1 202 Kabul Edildi
Yer: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14
API'yi kullandığınızda genellikle bir HTTP 202 durumu döndürür. İsteklerinize göre diğer olası durumlar için bkz. Durum.
| Kod | Description |
|---|---|
| 202 – Kabul Edildi | İsteğiniz kabul edildi. İsteğinizin durumunu denetlemek için konum üst bilgisinde sağlanan URL'yi sorgula. |
2. Adım: İstek durumunu denetleme
İsteğin durumunu denetlemek için "başarılı" veya "başarısız" durumuna sahip bir HTTP 200 yanıtı bekleyin. İstek başarılı olursa bildirim URL'si "resourceLocation" özniteliğinde sağlanır.
İşlem durumunu alma
İsteğin durumunu alır.
API isteği
İstek parametreleri
| Veri Akışı Adı | Dahil et | Zorunlu | Türü | Açıklama |
|---|---|---|---|---|
| operationId | İstek URI'si | Doğru | String | İstek durumunu denetlemek için benzersiz bir kimlik. Gerekli. |
İstek üst bilgisi
API için üst bilgi istemek için bkz . Güvenilirlik ve destek.
Request body
Yok.
Yanıt durumu
API, standart HTTP durumlarına ek olarak aşağıdaki HTTP durumunu döndürebilir:
| Kod | Description |
|---|---|
| 410 – Gitti | Bildirim bağlantısı yalnızca sunucu tarafından ayarlanan belirli bir süre boyunca etkindir. Bu süre geçtikten sonra bildirime erişmek için yeni bir istek göndermeniz gerekir. |
Yanıt yükü
API yanıt yükü aşağıdaki öznitelikleri içerir:
| Öznitelik | Zorunlu | Açıklama |
|---|---|---|
| id | True | Her yanıt için benzersiz bir kimlik. Gerekli. |
| durum | True | Değerler ve eylemler (gerekli): notstarted: "Retry-After" üst bilgisinde belirtilen süreyi bekleyin, ardından durumu denetlemek için başka bir çağrı yapın. running: "Retry-After" üst bilgisinde belirtilen süreyi bekleyin, ardından durumu denetlemek için başka bir çağrı yapın. başarılı: Veriler hazır. resourceLocation içinde belirtilen URI'yi kullanarak bildirim yükünü alın. başarısız oldu: İşlem kalıcı olarak başarısız oldu. Yeniden başlatın. |
| createdDateTime | True | İsteğin yapıldığı zaman. Gerekli. |
| lastActionDateTime | True | Durumun son değiştirildiği saat. Gerekli. |
| resourceLocation | False | Bildirim yükünün URI'sini. isteğe bağlı. |
| error | False | İşlem başarısız olursa, hata ayrıntıları JSON biçiminde sağlanır. isteğe bağlı. Aşağıdaki öznitelikler dahil edilebilir: ileti (Gerekli): Hatanın ayrıntılı açıklaması. code (Gerekli): Oluşan hatanın türü. |
Kaynak konumu nesnesi
| Öznitelik | Açıklama |
|---|---|
| id | Bildirim için benzersiz bir tanımlayıcı. |
| schemaVersion | Bildirim şemasının sürümü. |
| dataFormat | Faturalama veri dosyasının biçimi. compressedJSON: her blob JSON satır biçiminde veri içeren sıkıştırılmış bir dosya olduğunda veri biçimi. Her blobdan verileri almak için açın. |
| createdDateTime | Bildirim dosyasının oluşturulduğu tarih ve saat. |
| eTag | Bildirim verilerinin sürümü. Faturalama bilgilerinde yapılan bir değişiklik yeni bir değer oluşturur. |
| partnerTenantId | İş ortağının kiracısının kimliği. |
| rootDirectory | Dosyanın kök dizini. |
| sasToken | Dizinin altındaki tüm dosyaları okumanızı sağlayan SAS (paylaşılan erişim imzası) belirteci. |
| partitionType | "partitionValue" özniteliğine göre verileri birden çok bloba böler. Sistem, desteklenen sayıyı aşan bölümleri böler. Varsayılan olarak, veriler dosyadaki satır öğelerinin sayısına göre bölümlenmiştir. Bu değerler değişebileceğinden kodda sabit sayıda satır öğesi veya dosya boyutu ayarlamayın. |
| blobCount | Bu iş ortağı kiracı kimliği için toplam dosya sayısı. |
| bloblar | İş ortağı kiracı kimliği için dosya ayrıntılarını içeren "blob" nesnelerinden oluşan bir JSON dizisi. |
| blob nesnesi | Aşağıdaki ayrıntıları içeren bir nesne: |
| Adı | Blobun adı. |
| partitionValue | Dosyayı içeren bölüm. Büyük bölüm, her dosya aynı "partitionValue" içeren birden çok dosyaya bölünür. |
API isteği
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API yanıtı
Yanıt, verileri işlerken yeniden denemeden önce 10 saniye beklemenizi önerir.
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 isteği
(Önceki istekte 10 saniye sonra...)
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
API yanıtı
API, "resourceLocation" için "başarılı" durumunu ve URI'sini döndürür.
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. Adım: Azure blob depolamadan günlük derecelendirilmiş kullanım mutabakatı satır öğelerini indirme
"sasToken" ve "rootDirectory" özelliklerinden bildirim yükü API'sinin yanıtından paylaşılan erişim imzası (SAS) belirtecini ve blob depolama konumunu alın. Blob dosyasını indirip açmak için Azure Depolama SDK'sını/aracını kullanın. JSONLines biçimindedir.
Standart API yanıt durumları
BU HTTP durumlarını API yanıtından alabilirsiniz:
| Kod | Açıklama |
|---|---|
| 400 – Hatalı İstek | İstek eksik veya yanlış veriler içeriyor. Hata ayrıntıları için yanıt gövdesini denetleyin. |
| 401 – Yetkisiz | Arayan kimliği doğrulanmamıştır ve ilk çağrıyı yapmadan önce iş ortağı API hizmetiyle kimlik doğrulaması yapmanız gerekir. |
| 403 – Yasak | İsteği yapmak için gerekli yetkilendirmeye sahip değilsiniz. |
| 404 – Bulunamadı | İstenen kaynaklar sağlanan giriş parametreleriyle kullanılamaz. |
| 410 – Gitti | Bildirim bağlantısı zaman aşımına uğradı veya süresi doldu. Yeni bir istek gönderin. |
| 500 – İç Sunucu Hatası | API veya bağımlılıklarından biri şu anda isteği karşılayamaz. Daha sonra tekrar deneyin. |
| 5000 – Kullanılabilir veri yok | Sistem, sağlanan giriş parametreleri için veri içermiyor. |
Beta ve GA sürümlerini karşılaştırma
Beta ve genel kullanıma sunulan (GA) sürümleri arasındaki farkları anlamak için karşılaştırma tablosuna bakın. Beta sürümünü kullanıyorsanız GA sürümüne geçiş yapmak kolay olacaktır.
| Önemli bilgiler | Beta | Genel kullanılabilir |
|---|---|---|
| API konak uç noktası | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/ |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/ |
| HTTP yöntemi | POST | POST |
| Faturalanmamış günlük derecelendirilmiş kullanım API'si uç noktası | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export |
| Faturalanmamış günlük derecelendirilmiş kullanım API'sinin giriş parametreleri | API isteğinde parametreleri belirtmek için bunları istek URL'sinin sorgu dizesine ekleyin. Örneğin, period ve currencyCode parametrelerini belirtmek için istek URL'sine ekleyin ?period=current¤cyCode=usd . |
Giriş sağlamak için istek gövdesine bir JSON nesnesi ekleyin. JSON nesnesi aşağıdaki özellikleri içermelidir: * currencyCode: Faturanın para birimi kodu. Örneğin, ABD doları. * billingPeriod: Faturanın faturalama dönemi. Örneğin, geçerli. Aşağıda currencyCode ve billingPeriod özelliklerini içeren bir JSON nesnesi örneği verilmiştir: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Faturalanan günlük derecelendirmeli kullanım API'si uç noktası | https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId} |
https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export |
| Faturalanan günlük derecelendirmeli kullanım API'sinin giriş parametreleri | API isteğinde parametreleri belirtmek için istek URL'sine invoiceId değerini ekleyin. Ayrıca, tüm öznitelik kümesini almak için sorgu dizesine isteğe bağlı bir parça parametresi ekleyebilirsiniz. Örneğin, öznitelik kümesinin tamamını almak için istek URL'sine ekleyin ?fragment=full . |
Giriş sağlamak için istek gövdesine bir JSON nesnesi ekleyin. JSON nesnesi aşağıdaki özellikleri içermelidir: * invoiceId: Faturanın kimliği. Örneğin, G00012345. * attributeSet: Yanıta eklenecek öznitelik kümesi. Örneğin, tam. InvoiceId ve attributeSet özelliklerini içeren bir JSON nesnesi örneği aşağıda verilmiştir: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>} |
| Bildirim kaynağı | Bildirim kaynağını almak için ayrı bir GET /manifests/{id} yöntemi kullanın. | GET /manifests/{id} yöntemine ayrı bir çağrı gereksinimini ortadan kaldırarak resourceLocation içindeki ilgili bildirim kaynağını döndüren GET /operations/{Id} yöntemini kullanın. |
| Bildirim şemasındaki değişiklikler | ||
| "id": Kullanılamıyor | "id": Bildirim kaynağının benzersiz tanımlayıcısı. | |
| "sürüm": Kullanılabilir | "version": "schemaversion" olarak yeniden adlandırıldı. | |
| "dataFormat": Kullanılabilir | "dataFormat": Kullanılabilir. | |
| "utcCretedDateTime": Kullanılabilir | "utcCretedDateTime": "createdDateTime" olarak yeniden adlandırıldı. | |
| "eTag": Kullanılabilir | "eTag": Kullanılabilir. | |
| "partnerTenantId": Kullanılabilir | "partnerTenantId": Kullanılabilir | |
| "rootFolder": Kullanılabilir | "rootFolder": "rootDirectory" olarak yeniden adlandırıldı. | |
| "rootFolderSAS": Kullanılabilir | "rootFolderSAS": "sasToken" olarak yeniden adlandırıldı. Artık bir belirteç sağlar ve artık kök dizin yolunu içermiyor. Dizine erişmek için bunun yerine "rootDirectory" özelliğini kullanın. | |
| "partitionType": Kullanılabilir | "partitionType": Kullanılabilir. | |
| "blobCount": Kullanılabilir | "blobCount": Kullanılabilir. | |
| "sizeInBytes": Kullanılabilir | "sizeInBytes": Kullanılamaz. | |
| "bloblar": Kullanılabilir | "bloblar": Kullanılabilir. | |
| "blob nesnesi": Kullanılabilir | "blob nesnesi": Kullanılabilir. | |
| "name": Kullanılabilir | "name": Kullanılabilir. | |
| "partitionValue": Kullanılabilir | "partitionValue": Kullanılabilir. |
Günlük derecelendirilmiş kullanım mutabakatı satır öğesi öznitelikleri
"Tam" veya "temel" öznitelik kümeleri için günlük derecelendirilmiş kullanım mutabakat API'sinin döndürdiği öznitelikleri karşılaştırmak için aşağıdaki bilgilere bakın.
| Öznitelik | Tam | Temel |
|---|---|---|
| İş Ortağı Kimliği | evet | evet |
| PartnerName | evet | evet |
| CustomerId | evet | evet |
| CustomerName | evet | Yes |
| CustomerDomainName | evet | hayır |
| CustomerCountry | evet | hayır |
| MpnId | evet | hayır |
| Tier2MpnId | evet | hayır |
| InvoiceNumber | evet | evet |
| Ürün Kimliği | evet | evet |
| SkuId | evet | evet |
| AvailabilityId | evet | hayır |
| SkuName | evet | evet |
| ProductName | evet | hayır |
| PublisherName | evet | evet |
| PublisherId | evet | hayır |
| SubscriptionDescription | evet | hayır |
| SubscriptionId | evet | evet |
| ChargeStartDate | evet | evet |
| ChargeEndDate | evet | evet |
| UsageDate | evet | evet |
| MeterType | evet | hayır |
| MeterCategory | evet | hayır |
| MeterId | evet | hayır |
| MeterSubCategory | evet | hayır |
| MeterName | evet | hayır |
| MeterRegion | evet | hayır |
| Birim | evet | evet |
| ResourceLocation | evet | hayır |
| ConsumedService | evet | hayır |
| ResourceGroup | evet | hayır |
| ResourceURI | evet | evet |
| ChargeType | evet | evet |
| UnitPrice | evet | evet |
| Miktar | evet | evet |
| UnitType | evet | hayır |
| BillingPreTaxTotal | evet | evet |
| BillingCurrency | evet | evet |
| PricingPreTaxTotal | evet | evet |
| PricingCurrency | evet | evet |
| ServiceInfo1 | evet | hayır |
| ServiceInfo2 | evet | hayır |
| Etiketler | evet | hayır |
| AdditionalInfo | evet | hayır |
| EffectiveUnitPrice | evet | evet |
| PCToBCExchangeRate | evet | evet |
| EntitlementId | evet | evet |
| EntitlementDescription | evet | hayır |
| PartnerEarnedCreditPercentage | evet | hayır |
| CreditPercentage | evet | evet |
| CreditType | evet | evet |
| BenefitOrderID | evet | evet |
| Avantaj Kimliği | evet | hayır |
| BenefitType | evet | evet |
Önemli
v1'den API v2'ye geçerken bu değişiklikleri not edin.
Her özniteliğin adı büyük harfle başlar.
unitOfMeasure artık Unit oldu. Özniteliğin anlamı ve değeri aynıdır.
resellerMpnId artık Tier2MpnId'dir. Özniteliğin anlamı ve değeri aynıdır.
rateOfPartnerEarnedCredit adı ve değeri PartnerEarnedCreditPercentage olarak değiştirildi. Özniteliğin yeni adı ve değeri kesir yerine yüzdeyi yansıtır. Örneğin, 0,15 artık 15'tir.
rateOfCredit artık CreditPercentage oldu. Özniteliğin anlamı ve değeri değişti. Örneğin, 1,00 artık 100'dür.
Örnek kod
Daha fazla bilgi edinmek için bkz . İş Ortağı Merkezi API örnekleri: Faturalama mutabakat verilerini alma.
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin