Market tarifeli faturalama API'leri
Tarifeli faturalama API'leri, yayımcı bir teklifin İş Ortağı Merkezi'nde yayımlanması için özel ölçüm boyutları oluşturduğunda kullanılmalıdır. Kullanım olaylarını yaymak için özel boyutlara sahip bir veya daha fazla planı olan satın alınan teklifler için tarifeli faturalama API'leriyle tümleştirme gerekir.
Önemli
Kodunuzdaki kullanımı izlemeniz ve yalnızca temel ücretin üzerindeki kullanım için Microsoft'a kullanım olayları göndermeniz gerekir.
SaaS için özel ölçüm boyutları oluşturma hakkında daha fazla bilgi için bkz . SaaS tarifeli faturalama.
Yönetilen uygulama planıyla Azure Uygulaması bir teklif için özel ölçüm boyutları oluşturma hakkında daha fazla bilgi için bkz. Azure uygulama teklifi kurulum ayrıntılarınızı yapılandırma.
TLS 1.2 Notu Zorunlu Kılma
TLS sürüm 1.2 sürümü, HTTPS iletişimleri için en düşük sürüm olarak uygulanır. Kodunuzda bu TLS sürümünü kullandığınızdan emin olun. TLS sürüm 1.0 ve 1.1 kullanım dışıdır ve bağlantı girişimleri reddedilir.
Tarifeli faturalama tek kullanım olayı
Kullanım olayı API'sinin, belirli bir müşteri tarafından satın alınan plana yönelik etkin bir kaynağa (abone olunan) kullanım olaylarını yayması için yayımcı tarafından çağrılmalıdır. Kullanım olayı, teklifi yayımlarken yayımcı tarafından tanımlanan planın her özel boyutu için ayrı olarak yayılır.
Kaynak ve boyut başına takvim gününün her saati için yalnızca bir kullanım olayı yayılabilir. Bir saatte birden fazla birim tüketiliyorsa, saatte tüketilen tüm birimleri biriktirin ve ardından tek bir olayda yayın. Kullanım olayları yalnızca son 24 saat için yayılabilir. Herhangi bir zamanda 8:00 ile 8:59:59 (ve kabul edilir) arasında bir kullanım olayı yayar ve aynı gün için 8:00 ile 8:59:59 arasında ek bir olay gönderirseniz, yinelenen olay olarak reddedilir.
GÖNDERİ:https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
Sorgu parametreleri:
| Parametre | Öneri |
|---|---|
ApiVersion |
2018-08-31 kullanın. |
İstek üst bilgileri:
| İçerik türü | application/json komutunu kullanma |
|---|---|
x-ms-requestid |
İstemciden gelen isteği izlemek için benzersiz dize değeri, tercihen guid. Bu değer sağlanmazsa, yanıt üst bilgilerinde bir değer oluşturulur ve sağlanır. |
x-ms-correlationid |
İstemcideki işlem için benzersiz dize değeri. Bu parametre, istemci işleminden gelen tüm olayları sunucu tarafındaki olaylarla ilişkilendirmektedir. Bu değer sağlanmazsa, yanıt üst bilgilerinde bir değer oluşturulur ve sağlanır. |
authorization |
Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Biçimi, "Bearer <access_token>" belirteç değerinin yayımcı tarafından açıklandığı gibi alınmasıdır
|
İstek gövdesi örneği:
{
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
Azure Uygulaması Lication Managed Apps planları için Yönetilen resourceId Uygulama'dırresource group Id. Bunu getirmek için örnek bir betik, Azure tarafından yönetilen kimlikler belirtecini kullanma bölümünde bulunabilir.
SaaS teklifleri için SaaS resourceId abonelik kimliğidir. SaaS abonelikleri hakkında daha fazla bilgi için bkz . abonelikleri listeleme.
Yanıtlar
Kod: 200
Tamam. Kullanım emisyonu kabul edildi ve daha fazla işlem ve faturalama için Microsoft tarafında kaydedildi.
Yanıt yükü örneği:
{
"usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // this is the only value in case of single usage event
"messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
}
Kod: 400
Hatalı istek.
- Eksik veya geçersiz istek verileri sağlandı.
effectiveStartTimegeçmişte 24 saatten fazladır. Olayın süresi doldu.- SaaS aboneliği Abone olunan durumda değil.
Yanıt yükü örneği:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
Kod: 403
Yasak. Yetkilendirme belirteci sağlanmadı, geçersiz veya süresi doldu. veya istek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra Uygulama Kimliği ile yayımlanan bir teklif için aboneliğe erişmeye çalışır.
Kod: 409
Çakışma. Belirtilen kaynak kimliği, geçerli kullanım tarihi ve saati için bir kullanım olayı zaten başarıyla bildirildi.
Yanıt yükü örneği:
{
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
"quantity": 1.0,
"dimension": "dim1",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "plan1"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
}
Tarifeli faturalama toplu kullanım olayı
Toplu kullanım olayı API'si, aynı anda birden fazla satın alınan kaynağın kullanım olaylarını yaymanıza olanak tanır. Ayrıca, farklı takvim saatleri için oldukları sürece aynı kaynak için birkaç kullanım olayı yaymanıza da olanak tanır. Tek bir toplu işlemdeki en büyük olay sayısı 25'tir.
YAYINLA:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
Sorgu parametreleri:
| Parametre | Öneri |
|---|---|
ApiVersion |
2018-08-31 kullanın. |
İstek üst bilgileri:
| İçerik türü | application/json komutunu kullanma |
|---|---|
x-ms-requestid |
İstemciden gelen isteği izlemek için benzersiz dize değeri, tercihen guid. Bu değer sağlanmazsa, bir değer oluşturulur ve yanıt üst bilgilerinde sağlanır. |
x-ms-correlationid |
İstemcideki işlem için benzersiz dize değeri. Bu parametre, istemci işleminden gelen tüm olayları sunucu tarafındaki olaylarla ilişkilendirmektedir. Bu değer sağlanmazsa, bir değer oluşturulur ve yanıt üst bilgilerinde sağlanır. |
authorization |
Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Biçimi, Bearer <access_token> belirteç değerinin yayımcı tarafından açıklandığı gibi alınmasıdır
|
Not
İstek gövdesinde, kaynak tanımlayıcısının SaaS uygulaması ve özel ölçüm yayan Azure Yönetilen uygulaması için farklı anlamları vardır. SaaS Uygulamasının kaynak tanımlayıcısı şeklindedir resourceID. Azure Uygulaması Yönetilen Uygulamalar planlarının kaynak tanımlayıcısı şeklindedirresourceUri. Kaynak tanımlayıcıları hakkında daha fazla bilgi için bkz. Azure Market Tarifeli Faturalama- Kullanım olaylarını gönderirken doğru kimliği seçme.
SaaS teklifleri için SaaS resourceId abonelik kimliğidir. SaaS abonelikleri hakkında daha fazla bilgi için bkz . abonelikleri listeleme.
SaaS uygulamaları için istek gövdesi örneği:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
Azure Uygulaması Lication Managed Apps planları için Yönetilen resourceUri Uygulama resourceUsageId'dır. Bunu getirmek için örnek bir betik, Azure tarafından yönetilen kimlikler belirtecini kullanma bölümünde bulunabilir.
Azure Uygulaması ile yönetilen uygulamalar için istek gövdesi örneği:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
]
}
Yanıtlar
Kod: 200
Tamam. Toplu kullanım emisyonu kabul edildi ve daha fazla işlem ve faturalama için Microsoft tarafında kaydedildi. Yanıt listesi, toplu iş içindeki her olay için durumla birlikte döndürülür. Toplu iş olayının bir parçası olarak gönderilen her bir kullanım olayının yanıtlarını anlamak için yanıt yükünde yineleme yapmalısınız.
Yanıt yükü örneği:
{
"count": 2, // number of records in the response
"result": [
{ // first response
"usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // see list of possible statuses below,
"messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
"resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
},
{ // second response
"status": "Duplicate",
"messageTime": "0001-01-01T00:00:00",
"error": {
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>",
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
},
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
]
}
API yanıtında başvuruda bulunan durum kodunun BatchUsageEvent açıklaması:
| Durum kodu | Açıklama |
|---|---|
Accepted |
Kabul. |
Expired |
Kullanım süresi doldu. |
Duplicate |
Yinelenen kullanım sağlandı. |
Error |
Hata kodu. |
ResourceNotFound |
Sağlanan kullanım kaynağı geçersiz. |
ResourceNotAuthorized |
Bu kaynak için kullanım sağlama yetkiniz yok. |
ResourceNotActive |
Kaynak askıya alındı veya hiçbir zaman etkinleştirilmedi. |
InvalidDimension |
Kullanımın geçirildiği boyut bu teklif/plan için geçersiz. |
InvalidQuantity |
Geçirilen miktar 0'a eşit veya daha düşük. |
BadArgument |
Giriş eksik veya hatalı biçimlendirilmiş. |
Kod: 400
Hatalı istek. Toplu işlem 25'ten fazla kullanım olayı içeriyordu.
Kod: 403
Yasak. Yetkilendirme belirteci sağlanmadı, geçersiz veya süresi doldu. veya istek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra Uygulama Kimliği ile yayımlanan bir teklif için aboneliğe erişmeye çalışır.
Tarifeli faturalama kullanım olaylarını alma
Kullanım olaylarının listesini almak için kullanım olayları API'sini çağırabilirsiniz. ISV'ler, belirli bir yapılandırılabilir süre boyunca gönderilen kullanım olaylarını ve bu olayların API'yi çağırma noktasındaki durumunu görmek için bu API'yi kullanabilir.
AL: https://marketplaceapi.microsoft.com/api/usageEvents
Sorgu parametreleri:
| Parametre | Öneri |
|---|---|
| ApiVersion | 2018-08-31 kullanın. |
| usageStartDate | ISO8601 biçimde DateTime. Örneğin, 2020-12-03T15:00 veya 2020-12-03 |
| UsageEndDate (isteğe bağlı) | ISO8601 biçimde DateTime. Varsayılan = geçerli tarih |
| offerId (isteğe bağlı) | Varsayılan = tümü kullanılabilir |
| planId (isteğe bağlı) | Varsayılan = tümü kullanılabilir |
| boyut (isteğe bağlı) | Varsayılan = tümü kullanılabilir |
| azureSubscriptionId (isteğe bağlı) | Varsayılan = tümü kullanılabilir |
| reconStatus (isteğe bağlı) | Varsayılan = tümü kullanılabilir |
reconStatus'un olası değerleri:
| ReconStatus | Açıklama |
|---|---|
| Gönderildi | Henüz PC Analytics tarafından işlenmedi |
| Kabul edildi | PC Analytics ile eşleştirildi |
| Reddedildi | İşlem hattında reddedildi. Nedenini araştırmak için Microsoft desteğine başvurun. |
| Uyuşmaz -lığı | MarketplaceAPI ve İş Ortağı Merkezi Analizi miktarlarının ikisi de sıfırdan farklı olsa da eşleşmiyor |
İstek üst bilgileri:
| Content type | Application/json kullanma |
|---|---|
| x-ms-requestid | İstemciden gelen isteği izlemek için benzersiz dize değeri (tercihen GUID). Bu değer sağlanmazsa, yanıt üst bilgilerinde bir değer oluşturulur ve sağlanır. |
| x-ms-correlationid | İstemcideki işlem için benzersiz dize değeri. Bu parametre, istemci işleminden gelen tüm olayları sunucu tarafındaki olaylarla ilişkilendirmektedir. Bu değer sağlanmazsa, yanıt üst bilgilerinde bir değer oluşturulur ve sağlanır. |
| yetkilendirme | Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Biçim, Bearer <access_token> belirteç değerinin yayımcı tarafından alınmasıdır. Daha fazla bilgi için bkz.
|
Yanıtlar
Yanıt yükü örnekleri:
Kabul*
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Accepted",
"submittedQuantity": 17.0,
"processedQuantity": 17.0,
"submittedCount": 17
}
]
Gönderildi
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Submitted",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Uyuşmaz -lığı
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Mismatch",
"submittedQuantity": 17.0,
"processedQuantity": 16.0,
"submittedCount": 17
}
]
Reddedildi
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Rejected",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
Durum kodları
Kod: 403 Yasak. Yetkilendirme belirteci sağlanmadı, geçersiz veya süresi doldu. veya istek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra Uygulama Kimliği ile yayımlanan bir teklif için aboneliğe erişmeye çalışır.
Geliştirme ve test en iyi yöntemleri
Özel ölçüm emisyonunu test etmek için ölçüm API'siyle tümleştirmeyi uygulayın, yayımlanan SaaS teklifiniz için içinde birim başına sıfır fiyatla tanımlanan özel boyutlara sahip bir plan oluşturun. Ayrıca tümleştirmeye yalnızca sınırlı sayıda kullanıcının erişebilmesi ve tümleştirmeyi test edebilmesi için bu teklifi önizleme olarak yayımlayın.
Ayrıca, test sırasında bu plana erişimi sınırlı hedef kitleyle sınırlamak için mevcut bir canlı teklif için özel plan da kullanabilirsiniz.
Destek alma
Yayımcı destek seçeneklerini anlamak ve Microsoft ile bir destek bileti açmak için İş Ortağı Merkezi'ndeki ticari market programı için destek bölümünde yer alan yönergeleri izleyin.
Sonraki adımlar
Ölçüm hizmeti API'leri hakkında daha fazla bilgi için bkz . Market ölçüm hizmeti API'leri hakkında SSS.
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