Faturalanan fatura mutabakat API'si v2 (GA)
Şunlar için geçerlidir: İş Ortağı Merkezi (bağımsız bulutta kullanılamaz)
Yeni zaman uyumsuz API'miz, Azure blobları aracılığıyla faturalama ve mutabakat verilerinize erişmek için daha hızlı ve daha verimli bir yol sunar. Bağlantıyı saatlerce açık tutmak veya 2.000 satırlık öğeleri toplu olarak işlemek yerine artık iş akışınızı kolaylaştırabilirsiniz.
Yeni ticaret faturalanan fatura mutabakat API'sinde vale anahtarı ve zaman uyumsuz istek-yanıt desenleri gibi gelişmiş teknikler kullanılır. Bu API, tüm özniteliklere veya faturalanan fatura mutabakat verilerinin bir alt kümesine erişmek için kullanabileceğiniz bir paylaşılan erişim imzası (SAS) belirteci sağlar.
API'miz verimliliğinizi artırmak için iyileştirilmiş teknikler kullanır, böylece daha az çabayla daha hızlı sonuçlar elde edebilirsiniz. Veri erişiminizi basitleştirmek ve genel verimliliğinizi artırmak için bu API'yi benimseyin.
Not
Yeni API, İş Ortağı Merkezi API ana bilgisayarında barındırılmıyor. Bunun yerine, bunu MS Graph'ta Microsoft Graph API'sini kullanarak iş ortağı faturalama verilerini dışarı aktarma - Microsoft Graph v1.0 sayfasında bulabilirsiniz. Bu API'ye erişmek için aşağıdaki ayrıntılara bakın.
Önemli
Uygulamanızın iş ortağı faturalama verilerine erişmesine izin vermek için bu bağlantıyı izleyin ve Microsoft Graph'in kimlik doğrulaması ve yetkilendirme temel bilgilerini tanıyın.
Azure portalını veya Entra Yönetim merkezini kullanarak "PartnerBilling.Read.All" iznini atayabilirsiniz. Şunu yapabilirsiniz:
- Uygulamanızı Uygulama kayıtları bölümünün altındaki Microsoft Entra giriş sayfasına kaydedin.
- Gerekli izni vermek için API izinleri bölümünün altındaki Microsoft Entra App sayfasına gidin. "İzin ekle" seçeneğini belirleyin ve "PartnerBilling.Read.All" kapsamını seçin.
Bu adımları tamamlayarak uygulamanızın iş ortağı faturalama verilerine gerekli erişime sahip olduğundan emin olun.
API’ye genel bakış
Faturalanan yeni ticari fatura mutabakat satırı öğelerini zaman uyumsuz olarak almanıza yardımcı olmak için iki anahtar API uç noktası sunuyoruz. Başlamanıza yardımcı olacak kolaylaştırılmış bir kılavuz aşağıdadır:
Faturalanan fatura mutabakatı uç noktası
İlk olarak, bu API'yi kullanarak yeni ticaret faturalanmış fatura mutabakatı satır öğelerini getirin. İstekte bulunduğunuzda 202 HTTP durumu ve URL içeren bir konum üst bilgisi alırsınız. Başarı durumu ve bildirim URL'si elde edene kadar bu URL'yi düzenli olarak yoklama.
İşlem durumu uç noktası
Ardından, bu API'yi düzenli aralıklarla çağırarak işlem durumunu denetlemeye devam edin. Veriler hazır değilse yanıt, yeniden denemeden önce ne kadar süre beklendiğini belirten bir Yeniden Deneme-Sonra üst bilgisi içerir. İşlem tamamlandıktan sonra, kullanım verilerini indirmek için depolama klasörü bağlantısına sahip bir bildirim kaynağı alırsınız. Yanıt, aktarım hızını artırmak ve G/Ç paralelliği sağlamak için dosyaları bölümlere ayırır.
Bu adımları izleyerek fatura mutabakat sürecinizi verimli bir şekilde yönetebilirsiniz.
Sıralı diyagram
Burada, yeni ticari fatura mutabakat verilerini indirme adımlarını gösteren bir sıralı diyagram yer alır.
Kullanıcı eylem dizisi
Faturalanan fatura mutabakat verilerini almak için şu adımları izleyin:
1. Adım: İstek gönderme
API uç noktasına bir POST isteği gönderin.
Faturalanan fatura mutabakat satırı öğelerini alma
API isteği
POST https://graph.microsoft.com/v1.0/reports/partners/billing/reconciliation/billed/export
Accept: application/json
Content-Type: application/json
{
"invoiceId": "G016907411",
"attributeSet": "basic"
}
Sorgu parametreleri
Yok
Request body
İstek üst bilgileri
Microsoft Graph'i kullanmaya yönelik en iyi yöntemler altında listelenen adımları kullanarak API için üst bilgileri isteyin. Bu yönergeleri izleyerek, uygulamanız için güvenilirlik ve destek sağlarsınız. Bu adımda ayrıntılara dikkat edin, sorunsuz tümleştirme ve en iyi performans için çok önemlidir.
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 genellikle HTTP 202 durumuyla yanıt verir. İsteklerinize bağlı olarak başka durumlarla da karşılaşabilirsiniz. Bu durumlar Standart API yanıt durumları bölümünde listelenir.
| 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 izlemek için "başarılı" veya "başarısız" ifadesini gösteren bir HTTP 200 yanıtı aldığınızdan emin olun. Başarılı olursa bildirim URL'sini "resourceLocation" özniteliğinde bulursunuz. Bu öznitelik, gerekli bilgilere erişmek için bir uç nokta sağlar.
İşlem durumunu alma
İsteğin durumunu alır.
API isteği
GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>
İ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
Microsoft Graph'i kullanmaya yönelik en iyi yöntemler altında listelenen adımları kullanarak API için üst bilgileri isteyin. Bu yönergeleri izleyerek, uygulamanız için güvenilirlik ve destek sağlarsınız. Bu adımda ayrıntılara dikkat edin, sorunsuz tümleştirme ve en iyi performans için çok önemlidir.
Request body
Yok.
Yanıt durumu
Standart API yanıt durumlarında listelenen standart HTTP durumlarının dışında, API aşağıdaki HTTP durumunu da döndürebilir:
| Kod | Description |
|---|---|
| 410 – Gitti | Bildirim bağlantısının süresi belirli bir süreden sonra dolar. Bildirim bağlantısını yeniden almak için yeni bir istek gönderin. |
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 tanımlayıcı 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 | Durum en son değiştiğinde. Gerekli. |
| resourceLocation | False | Bildirim yükünün URI'sini. İsteğe bağlı. |
| hata | False | JSON biçiminde sağlanan hatalar hakkındaki ayrıntılar. İsteğe bağlı. Eklenen öznitelikler: ileti: Hatanın açıklaması. kod: 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 her değişiklik olduğunda yeni bir değer oluşturulur. |
| partnerTenantId | İş ortağının kiracısının Microsoft Entra 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. Kodda sabit sayıda satır öğesi veya dosya boyutu ayarlamayın çünkü bu değerler değişebilir. |
| 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: name ve partitionValue |
| Adı | Blobun adı. |
| partitionValue | Dosyayı içeren bölüm. Dosyayı içeren bölüm. Büyük bölümler, her birinde aynı "partitionValue" içeren birden çok dosyaya ayrılı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, verileriniz işlemeye devam ederken 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: Faturalanan fatura mutabakat satırı öğelerini Azure blob depolama alanından indirme
İlk olarak, paylaşılan erişim imzası (SAS) belirtecini ve blob depolama konumunu almanız gerekir. Bu ayrıntıları bildirim yükü API'sinin "sasToken" ve "rootDirectory" özelliklerinde bulabilirsiniz. Ardından blob dosyasını indirip açmak için Azure Depolama SDK'sını /aracını kullanın. JSONLines biçimindedir.
İpucu
Örnek kodumuzu gözden geçirin. Azure blob dosyasını indirmeyi ve yerel veritabanınıza sıkıştırmayı gösterir.
Standart API yanıt durumları
BU HTTP durumlarını API yanıtından alabilirsiniz:
| Kod | Description |
|---|---|
| 400 – Hatalı İstek | İstek eksik veya yanlış veriler içeriyor. Hata ayrıntıları için yanıt gövdesini denetleyin. |
| 401 – Yetkisiz | İlk çağrıyı yapmadan önce kimlik doğrulaması gereklidir. İş ortağı API hizmetiyle kimlik doğrulaması yapın. |
| 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ı artık geçerli veya etkin değil. Yeni bir istek gönderin. |
| 500 – İç Sunucu Hatası | API veya bağımlılıkları ş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. |
Faturalanan fatura mutabakat satırı madde öznitelikleri
Faturalanan fatura mutabakat API'sinin "tam" veya "temel" öznitelik kümeleri için döndürdiği öznitelikleri karşılaştırmak için aşağıdaki tabloya bakın. Bu öznitelikler hakkında daha fazla bilgi edinmek için bkz . Keşif dosyasını kullanma.
| Öznitelik | Tam | Temel |
|---|---|---|
| İş Ortağı Kimliği | evet | evet |
| CustomerId | evet | evet |
| CustomerName | evet | evet |
| CustomerDomainName | evet | hayır |
| CustomerCountry | evet | hayır |
| InvoiceNumber | evet | evet |
| MpnId | evet | hayır |
| Tier2MpnId | evet | evet |
| OrderId | evet | evet |
| OrderDate | evet | evet |
| Ürün Kimliği | evet | evet |
| SkuId | evet | evet |
| AvailabilityId | evet | evet |
| SkuName | evet | hayır |
| ProductName | evet | evet |
| ChargeType | evet | evet |
| UnitPrice | evet | evet |
| Miktar | evet | hayır |
| Alt Toplam | evet | evet |
| TaxTotal | evet | evet |
| Toplam | evet | evet |
| Para birimi | evet | evet |
| PriceAdjustmentDescription | evet | evet |
| PublisherName | evet | evet |
| PublisherId | evet | hayır |
| SubscriptionDescription | evet | hayır |
| SubscriptionId | evet | evet |
| ChargeStartDate | evet | evet |
| ChargeEndDate | evet | evet |
| TermAndBillingCycle | evet | evet |
| EffectiveUnitPrice | evet | evet |
| UnitType | evet | hayır |
| AlternateId | evet | hayır |
| BillableQuantity | evet | evet |
| BillingFrequency | evet | hayır |
| PricingCurrency | evet | evet |
| PCToBCExchangeRate | evet | evet |
| PCToBCExchangeRateDate | evet | hayır |
| MeterDescription | evet | hayır |
| ReservationOrderId | evet | evet |
| CreditReasonCode | evet | evet |
| SubscriptionStartDate | evet | evet |
| SubscriptionEndDate | evet | evet |
| ReferenceId | evet | evet |
| ProductQualifiers | evet | hayır |
| PromotionId | evet | evet |
| ProductCategory | evet | evet |
Örnek kod
Bu API'yi kullanmak için C# örnek kodunu içeren aşağıdaki bağlantıya bakın.
İş Ortağı-Merkezi Faturalama-Mutabakat Örnekleri: İş Ortağı Merkezi'nden (github.com) Faturalama mutabakat verilerini almaya yönelik API örnekleri.