Faturalanan fatura mutabakat API'si v2 (GA)
Şunlar için geçerlidir: İş Ortağı Merkezi (bağımsız bulutta kullanılamaz)
Zaman uyumsuz API'miz, 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 ile bir bağlantıyı saatlerce açık tutmanız veya aynı anda 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 faturalanmış fatura mutabakat API'mizi iyileştirdik. 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.
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.
Bu API'yi artık yalnızca MS Graph genel/genel bulutu için kullanabilirsiniz. henüz Azure Kamu, Azure Almanya veya Azure China 21Vianet için kullanılamaz.
API’ye genel bakış
Faturalanan yeni ticari fatura mutabakat verilerini zaman uyumsuz olarak almak için iki API uç noktası kullanın. Süreç şu şekildedir:
Faturalanan fatura mutabakatı uç noktası
Bu API'yi yeni ticaret faturalanmış fatura mutabakat satırı öğelerini almak için kullanın. API, 202 HTTP durumunu ve URL içeren bir konum üst bilgisini döndürür. 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
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.
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 diğer olası durumlar bu makaledeki Standart API yanıt durumlarında listelenmiştir.
| 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 "resourceLocation" özniteliğinde bildirim URL'sini alırsınız.
İş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.
Request body
Yok.
Yanıt durumu
Bu makaledeki Standart API yanıt durumlarında listelenen standart HTTP durumlarına ek olarak, API aşağıdaki HTTP durumunu 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 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 dahildir: ileti: Hatanın ayrıntılı açıklaması. kod: 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. 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: 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. |
| 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, 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 verilerini Azure blob depolama alanından 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ı indirmek ve sıkıştırmasını açmak için Azure Depolama SDK'sı/aracı. JSONLines biçimindedir.
Standart API yanıt durumları
BU HTTP durumlarını API'nin 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 | 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ı artık geçerli veya etkin değil. 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. |
Faturalanan fatura mutabakatı veri ö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.
| Ö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
API'yi kullanma yönergeleri için C# dilinde örnek kod 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.
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