Aracılığıyla paylaş

Pazaryeri ölçüme dayalı 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. Özel boyutlara sahip bir veya daha fazla plan sunan satın alınan teklifler için, kullanım olaylarını yaymak amacıyla tarifeli faturalama API'leriyle entegrasyon gereklidir.

Ö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ının nasıl oluşturulacağını öğrenmek için bkz. SaaS tarifeli faturalama.

Yönetilen planlı bir Azure uygulaması için özel ölçüm ayarlamayı öğrenmek için bkz. Azure uygulama teklifi kurulum ayrıntılarınızı yapılandırma.


TLS 1.2 Notunu Uygulama

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 tekil kullanım etkinliği

Kullanım olayı API'si, belirli bir müşteri tarafından satın alınan plan için abonelik yapılan aktif bir kaynak üzerinde kullanım olaylarını bildirmesi amacıyla 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 Tavsiye
ApiVersion 2018-08-31 tarihini kullanın.

İstek başlıkları:

İçerik türü application/json kullanma
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz bir dize değeri, tercihen bir GUID. Bu değer sağlanmazsa, biri oluşturulup yanıt üst bilgilerine eklenir.
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ğlanmadığında, yanıt üst bilgilerinde otomatik olarak bir değer oluşturulup sağlanacaktır.
authorization Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Format, belirteç değeri yayımcı tarafından açıklandığı gibi alındığında "Bearer <access_token>" şeklindedir.

İ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 Yönetilen Uygulama planları için, resourceId Yönetilen Uygulama resource group Id'dir. Bunu almak için bir örnek betik, Azure tarafından yönetilen kimlikler belirtecini kullanma bölümünde bulunabilir.

SaaS teklifleri için resourceId SaaS abonelik kimliğidir. SaaS abonelikleri hakkında daha fazla bilgi için bkz. abonelikleri listeleme.

Yanıt

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.

  • Sağlanan istek verileri eksik veya geçersiz.
  • effectiveStartTime, geçmişte 24 saatten daha uzun bir süre önceydi. Olayın süresi doldu.
  • SaaS aboneliği Abone statüsünde 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: 401 Yetkisiz. Yetkilendirme belirteci geçersiz veya süresi dolmuş. İstek, kimlik doğrulama belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, sağlanmadı veya yetersiz izinlerle sağlandı. Lütfen geçerli bir yetkilendirme belirteci sağladığıdan emin olun.

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.

Kod: 500 İç sunucu hatası. API çağrısını yeniden deneyin. Hata devam ederse microsoft desteği başvurun.

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 işleme kullanım etkinliği

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 Tavsiye
ApiVersion 2018-08-31 tarihini kullanın.

İstek başlıkları:

İçerik türü application/json kullanma
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz bir dize değeri, tercihen bir GUID. Bu değer sağlanmazsa, bir değer oluşturulur ve yanıt üst bilgilerine eklenir.
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 bilgilerine eklenir.
authorization Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Format, belirteç değeri yayımcı tarafından açıklandığı gibi alındığında Bearer <access_token> şeklindedir.

Not

İstek gövdesinde, kaynak tanımlayıcısının SaaS uygulaması ve özel ölçüm üreten Azure Yönetilen uygulaması için farklı anlamları vardır. SaaS Uygulamasının kaynak tanımlayıcısı resourceID. Azure Yönetilen Uygulama Planları'nın kaynak kimliği resourceUri. 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 resourceId SaaS 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 Yönetilen Uygulama Planları için, resourceUri Yönetilen Uygulama resourceUsageId'dir. Bunu almak için bir örnek betik, Azure tarafından yönetilen kimlikler belirtecini kullanma bölümünde bulunabilir.

Azure Uygulaması tarafından 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ıt

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 olayın bir parçası olarak gönderilen her bir kullanım olayına verilen yanıtları anlamak için yanıt yükünü yinelemelisiniz.

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"
    }
  ]
}

BatchUsageEvent API yanıtında başvuruda bulunan durum kodunun açıklaması:

Durum kodu Açıklama
Accepted Kabul edildi.
Expired Kullanım süresi doldu.
Duplicate Aynı 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 aktarıldığı 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: 401 Yetkisiz. Yetkilendirme belirteci geçersiz veya süresi dolmuş. İstek, kimlik doğrulama belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, sağlanmadı veya yetersiz izinlerle sağlandı. Lütfen geçerli bir yetkilendirme belirteci sağladığıdan emin olun.

Kod: 500 İç sunucu hatası. API çağrısını yeniden deneyin. Hata devam ederse microsoft desteği başvurun.

Tarifeli faturalama kullanım olaylarını geri 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?api-version=<ApiVersion>&usageStartDate=<usageStartDate>

Sorgu parametreleri:

Parametre Tavsiye
ApiVersion 2018-08-31 tarihini kullanın.
kullanımBaşlangıçTarihi ISO8601 formatında tarih ve saat. Örneğin, 2020-12-03T15:00 veya 2020-12-03
UsageEndDate (isteğe bağlı) ISO8601 formatında tarih ve saat. 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önderilmektedir Henüz PC Analytics tarafından işlenmedi
Kabul edildi PC Analytics ile eşleştirildi
Reddedilmiş İşlem hattında reddedildi. Nedenini araştırmak için Microsoft desteğine başvurun.
Uyumsuzluk MarketplaceAPI ve İş Ortağı Merkezi Analizi miktarlarının ikisi de sıfırdan farklı olsa da eşleşmiyor

İstek üst bilgileri:

İçerik türü Application/json kullanma
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz dize değeri (tercihen GUID). Bu değer sağlanmadığında, yanıt üst bilgilerinde otomatik olarak bir değer oluşturulup sağlanacaktı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ğlanmadığında, yanıt üst bilgilerinde otomatik olarak bir değer oluşturulup sağlanacaktır.
izin Bu API çağrısını yapan ISV'yi tanımlayan benzersiz bir erişim belirteci. Belirteç değeri yayımcı tarafından alındığında biçimi Bearer <access_token> şeklindedir. Daha fazla bilgi için bkz:

Yanıt

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önderilmektedir

[
  {
    "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
  }
]

Reddedilmiş

[
  {
    "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: 401 Yetkisiz. Yetkilendirme belirteci geçersiz veya süresi dolmuş. İstek, kimlik doğrulama belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, sağlanmadı veya yetersiz izinlerle sağlandı. Lütfen geçerli bir yetkilendirme belirteci sağladığıdan emin olun.

Kod: 500 İç sunucu hatası. API çağrısını yeniden deneyin. Hata devam ederse microsoft desteği başvurun.

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

Microsoft ile bir destek bileti açmak ve yayımcı destek seçeneklerini anlamak için İş Ortağı Merkezi'ndeki ticari market programı için destek için verilen yönergeleri izleyin.

İlgili içerik

Ölçüm hizmeti API'leri hakkında daha fazla bilgi için, Marketplace ölçüm hizmeti API'leri SSS kısmına bakın.