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.

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:

İstek üst bilgileri:

İ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ı.
• effectiveStartTime geç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
Anlaşmazlık. 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:

İstek üst bilgileri:

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ı:

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:

reconStatus'un olası değerleri:

İstek üst bilgileri:

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 alın

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.

İlgili içerik

Ölçüm hizmeti API'leri hakkında daha fazla bilgi için bkz . Market ölçüm hizmeti API'leri hakkında SSS.