Microsoft ticari marketinde SaaS karşılama Abonelik API'leri v2

  • Makale

Bu makalede SaaS karşılama aboneliği API'lerinin 2. sürümü açıklanmaktadır.

Satın alınan aboneliği çözme

Çözüm uç noktası, yayımcının satın alma tanımlama belirtecini ticari marketten (Satın alınan ancak henüz etkinleştirilmemiş belirteç olarak adlandırılır) kalıcı bir satın alınan SaaS abonelik kimliğine ve ayrıntılarına değiştirmesine olanak tanır.

Müşteri iş ortağının giriş sayfası URL'sine yeniden yönlendirildiğinde, müşteri tanımlama belirteci bu URL çağrısında belirteç parametresi olarak geçirilir. İş ortağının bu belirteci kullanması ve bu belirteci çözmek için istekte bulunması beklenir. Çözüm API'si yanıtı, satın alma işlemini benzersiz olarak tanımlamak için SaaS abonelik kimliğini ve diğer ayrıntıları içerir. Giriş sayfası URL çağrısıyla sağlanan belirteç 24 saat geçerlidir. Aldığınız belirtecin süresi dolduysa, son kullanıcıya aşağıdaki yönergeleri sağlamanızı öneririz:

"Bu satın alma işlemi belirlenemedi. Bu SaaS aboneliğini Azure portalında veya Microsoft 365 Yönetici Merkezi'nde yeniden açın ve "Hesabı Yapılandır" veya "Hesabı Yönet" seçeneğini yeniden seçin."

Çözümle API'sini çağırmak, tüm desteklenen durumlarda SaaS aboneliklerinin abonelik ayrıntılarını ve durumunu döndürür.

Yayınla https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.
x-ms-marketplace-token Çözümlenmesi gereken satın alma tanımlama belirteci parametresi. Belirteç, müşteri SaaS iş ortağının web sitesine yönlendirildiğinde giriş sayfası URL çağrısına geçirilir (örneğin: https://contoso.com/signup?token=<token><authorization_token>).

Kodlanan belirteç değeri giriş sayfası URL'sinin bir parçasıdır, bu nedenle bu API çağrısında parametre olarak kullanılmadan önce kodunun çözülmesi gerekir.

URL'de kodlanmış bir dize örneği aşağıda verilmiştir: contoso.com/signup?token=ab%2Bcd%2Fef, burada belirtecin olduğu yerdir ab%2Bcd%2Fef. Kodu çözülen belirtecin kodu şu şekildedir: Ab+cd/ef

Yanıt kodları:

Kod: 200 Sağlanana göre x-ms-marketplace-token benzersiz SaaS abonelik tanımlayıcılarını döndürür.

Yanıt gövdesi örneği:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Kod: 400 Hatalı istek. x-ms-marketplace-token eksik, hatalı biçimlendirilmiş, geçersiz veya süresi dolmuş.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle yayımlanmış bir teklif için SaaS aboneliğine erişmeye çalışır.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

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

Aboneliği etkinleştirme

SaaS hesabı bir son kullanıcı için yapılandırıldıktan sonra yayımcının Microsoft tarafında Aboneliği Etkinleştirme API'sini çağırması gerekir. Bu API çağrısı başarılı olmadığı sürece müşteri faturalandırılamaz.

Yayınla https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir dize değeri. Bu dize, 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

Yanıt kodları:

Kod: 200 Aboneliği güncelleştirme isteği ve "Abone oldu" olarak işaretleme isteği alındı. Bağımsız Yazılım Satıcıları (ISV'ler) birkaç dakika sonra aboneliğin durumunu denetleyebiliyor (abonelik durumunu denetlemek için Get işlemi için okumaya devam edin). Bu size aboneliğin başarıyla güncelleştirilip güncelleştirilmediğine ilişkin kesin bir yanıt verir. Abone olunamaması otomatik olarak bir "Abonelikten çık" web kancası gönderir.

Bu çağrı için yanıt gövdesi yok.

Kod: 400 Hatalı istek: doğrulama başarısız oldu.

  • SaaS aboneliği Askıya alındı durumunda.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle yayımlanmış bir teklif için SaaS aboneliğine erişmeye çalışır.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

Kod: 404 Bulunamadı. SaaS aboneliği Aboneliği kaldırılmış durumdadır.

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

Tüm aboneliklerin listesini alma

Bu API, yayımcının ticari markette yayımlamış olduğu tüm teklifler için satın alınan tüm SaaS aboneliklerinin listesini alır. Tüm olası durumlardaki SaaS abonelikleri döndürülür. Abonelikten kaldırılan SaaS abonelikleri de döndürülür çünkü bu bilgiler Microsoft tarafında silinmez.

API sayfa başına 100 sayfalandırılmış sonuç döndürür.

Al https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
continuationToken İsteğe bağlı parametre. Sonuçların ilk sayfasını almak için boş bırakın. Sonraki sayfayı almak için parametresinde @nextLink döndürülen değeri kullanın.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

Yanıt kodları:

Kod: 200 Yayımcının yetkilendirme belirtecini temel alarak bu yayımcı tarafından yapılan tüm teklifler için mevcut tüm aboneliklerin listesini döndürür.

Yanıt gövdesi örneği:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Bu yayımcı için satın alınmış SaaS aboneliği bulunmazsa boş yanıt gövdesi döndürülür.

Kod: 403 Yasak. Yetkilendirme belirteci kullanılamıyor, geçersiz veya süresi dolmuş.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

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

Abonelik al

Bu API, yayımcının ticari markette yayımlayacağı bir SaaS teklifi için belirtilen satın alınan SaaS aboneliğini alır. Belirli bir SaaS aboneliği için tüm aboneliklerin listesini almak için kullanılan API'yi çağırmak yerine kimliğine göre tüm kullanılabilir bilgileri almak için bu çağrıyı kullanın.

Al https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

Yanıt kodları:

Kod: 200 Sağlanana göre bir SaaS aboneliğinin subscriptionId ayrıntılarını döndürür.

Yanıt gövdesi örneği:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, yetkilendirme 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.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

Kod: 404 Bulunamadı. Belirtilen subscriptionId ile SaaS aboneliği bulunamıyor.

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

Kullanılabilir planları listeleme

Bu API, bu teklifin belirli bir satın alma işlemiyle subscriptionId tanımlanan bir SaaS teklifi için tüm planları alır. SaaS aboneliğinin yararlanıcısının abonelik için güncelleştirebileceği tüm özel ve genel planların listesini almak için bu çağrıyı kullanın. Döndürülen planlar, zaten satın alınan planla aynı coğrafyada kullanılabilir.

Bu çağrı, önceden satın alınana ek olarak bu müşteri için kullanılabilen planların listesini döndürür. Liste, yayımcı sitesindeki son kullanıcıya sunulabilir. Son kullanıcı, abonelik planını döndürülen listedeki planlardan herhangi biriyle değiştirebilir. Planı listede olmayan bir plana değiştirmek işe yaramaz.

Bu API ayrıca ilişkili etkin özel teklif kimliğini de alır (API'yi planId filtresiyle çağırırsanız). planId filtresiyle API çağrılması, sourceOffers düğümü altındaki yanıt gövdesinde etkin özel teklif kimliği GUID'lerini gösterir. Filtre parametresinde geçirilen plan Kimliği, müşterinin satın aldığı plan Kimliği ile eşleşmelidir.

Al https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.
planId (Optional) Getirmek istediğiniz belirli bir planın plan kimliği. Bu isteğe bağlıdır ve yoksayılırsa tüm planları döndürür.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

Yanıt kodları:

Kod: 200 Zaten satın alınmış olan saas aboneliği de dahil olmak üzere mevcut bir SaaS aboneliği için tüm kullanılabilir planların listesini döndürür.

Geçersiz (isteğe bağlı) plan Kimliği geçirilmesi, boş plan listesi döndürür.

Yanıt gövdesi örneği:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Kod: 404 Bulunamadı. subscriptionId bulunamadı.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, yetkilendirme belirtecini oluşturmak için kullanılandan farklı bir Microsoft Entra uygulama kimliğiyle aboneliği kaldırılmış veya yayımlanmış bir teklif için SaaS aboneliğine erişmeye çalışabilir.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

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

Abonelikte planı değiştirme

SaaS aboneliği için satın alınan mevcut planı yeni bir plana (genel veya özel) güncelleştirmek için bu API'yi kullanın. Ticari markette satın alınan saas aboneliği için yayımcı tarafında bir plan değiştirildiğinde yayımcının bu API'yi çağırması gerekir.

Bu API yalnızca Etkin abonelikler için çağrılabilir. Herhangi bir plan, diğer mevcut planlara (genel veya özel) değiştirilebilir, ancak kendisine değiştirilemez. Özel planlar için müşterinin kiracısının İş Ortağı Merkezi'nde planın hedef kitlesinin bir parçası olarak tanımlanması gerekir.

Yama https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

İstek yükü örneği:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Yanıt kodları:

Kod: 202 Planı değiştirme isteği zaman uyumsuz olarak kabul edildi ve işlendi. İş ortağının değişiklik planı isteğinin başarısını veya başarısızlığını belirlemek için İşlem Konumu URL'sini yoklaması beklenir. İşlem için Son Durum Başarısız, Başarılı veya Çakışma alınana kadar yoklama birkaç saniyede bir yapılmalıdır. Son işlem durumu hızlı bir şekilde döndürülmelidir, ancak bazı durumlarda birkaç dakika sürebilir.

İş ortağı ayrıca ticari market tarafında eylem başarıyla tamamlanmaya hazır olduğunda web kancası bildirimi alır. Ancak o zaman yayımcının plan değişikliğini yayımcı tarafında yapması gerekir.

Yanıt üst bilgileri:

Parametre Value
Operation-Location İşlemin durumunu almak için URL. Örneğin https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Kod: 400 Hatalı istek: doğrulama hataları.

  • Yeni plan mevcut değil veya bu özel SaaS aboneliği için kullanılamıyor.
  • Yeni plan, geçerli planla aynıdır.
  • SaaS aboneliğinin durumu Abone olunmuyor.
  • SaaS aboneliği için güncelleştirme işlemi'ne allowedCustomerOperationsdahil değildir.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, yetkilendirme 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.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

Kod: 404 Bulunamadı. ile subscriptionId SaaS aboneliği bulunamadı.

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

Not

Plan veya koltuk miktarı aynı anda değiştirilebilir, her ikisi de değiştirilemez.

Bu API yalnızca son kullanıcıdan değişiklik için açık onay aldıktan sonra çağrılabilir.

SaaS aboneliğindeki koltuk miktarını değiştirme

SaaS aboneliği için satın alınan koltuk miktarını güncelleştirmek (artırmak veya azaltmak) için bu API'yi kullanın. Ticari markette oluşturulan SaaS aboneliği için yayımcı tarafından koltuk sayısı değiştirildiğinde yayımcının bu API'yi çağırması gerekir.

Koltuk miktarı geçerli planda izin verilen miktardan fazla olamaz. Bu durumda, yayımcının koltuk miktarını değiştirmeden önce planı değiştirmesi gerekir.

Yama https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

İstek yükü örneği:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Yanıt kodları:

Kod: 202 Miktarı değiştirme isteği kabul edildi ve zaman uyumsuz olarak işlendi. İş ortağının değişiklik miktarı isteğinin başarısını veya başarısızlığını belirlemek için İşlem Konumu URL'sini yoklaması beklenir. İşlem için Son Durum Başarısız, Başarılı veya Çakışma alınana kadar yoklama birkaç saniyede bir yapılmalıdır. Son işlem durumu hızlı bir şekilde döndürülmelidir, ancak bazı durumlarda birkaç dakika sürebilir.

İş ortağı ayrıca ticari market tarafında eylem başarıyla tamamlanmaya hazır olduğunda web kancası bildirimi alır. Ancak o zaman yayımcı, yayımcı tarafında miktar değişikliği yapmalıdır.

Yanıt üst bilgileri:

Parametre Value
Operation-Location İşlemin durumunu almak için kaynağa bağlanın. Örneğin, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kod: 400 Hatalı istek: doğrulama hataları.

  • Yeni miktar geçerli plan sınırından büyük veya daha düşük.
  • Yeni miktar eksik.
  • Yeni miktar, geçerli miktarla aynıdır.
  • SaaS Aboneliği durumu Abone değil.
  • SaaS aboneliği için güncelleştirme işlemi'ne allowedCustomerOperationsdahil değildir.

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya sağlanmadı. İstek, geçerli yayımcıya ait olmayan bir aboneliğe erişmeye çalışır.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

Kod: 404 Bulunamadı. ile subscriptionId SaaS aboneliği bulunamadı.

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

Not

Her ikisi de değil, yalnızca bir plan veya miktar aynı anda değiştirilebilir.

Bu API yalnızca değişiklik için son kullanıcıdan açık onay aldıktan sonra çağrılabilir.

Aboneliği iptal etme

Belirtilen SaaS aboneliğinin aboneliğini kaldırmak için bu API'yi kullanın. Yayımcının bu API'yi kullanması gerekmez ve müşterilerin SaaS aboneliklerini iptal etmek için ticari markete yönlendirilmesi önerilir.

Yayımcı, ticari markette satın alınan saas aboneliğinin iptalini yayımcı tarafında uygulamaya karar verirse, bu API'yi çağırması gerekir. Bu çağrı tamamlandıktan sonra aboneliğin durumu Microsoft tarafında Abonelikten çıkarılır.

Satın alma işlemini izleyen 72 saat içinde abonelik iptal edilirse müşteri faturalandırılamaz.

Önceki yetkisiz kullanım süresinden sonra bir abonelik iptal edilirse müşteri faturalandırılır. Müşteri, iptal işleminin hemen ardından Microsoft tarafında SaaS aboneliğine erişimi kaybeder.

Silmek https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Sorgu parametreleri:

Parametre Value
ApiVersion 2018-08-31 kullanın.
subscriptionId Satın alınan SaaS aboneliğinin benzersiz tanımlayıcısı. Bu kimlik, Çözümle API'si kullanılarak ticari market yetkilendirme belirteci çözümlendikten sonra elde edilir.

İstek üst bilgileri:

Parametre Value
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için tercihen GUID olan benzersiz bir dize değeri. 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 bir 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 yayımcıyı tanımlayan benzersiz bir erişim belirteci. Biçim, "Bearer <access_token>" Microsoft Entra uygulamasına dayalı belirteç alma bölümünde açıklandığı gibi belirteç değerinin yayımcı tarafından alınmasıdır.

Yanıt kodları:

Kod: 202 Abonelikten çıkma isteği kabul edildi ve zaman uyumsuz olarak işlendi. İş ortağının bu isteğin başarılı veya başarısız olduğunu belirlemek için İşlem Konumu URL'sini yoklaması beklenir. İşlem için Son Durum Başarısız, Başarılı veya Çakışma alınana kadar yoklama birkaç saniyede bir yapılmalıdır. Son işlem durumu hızlı bir şekilde döndürülmelidir, ancak bazı durumlarda birkaç dakika sürebilir.

İş ortağı ayrıca ticari market tarafında eylem başarıyla tamamlandığında web kancası bildirimi alır. Ancak yayımcının yayımcı tarafında aboneliği iptal etmesi gerekir.

Kod: 200 Abonelik zaten Aboneliği kaldırılmış durumda.

Yanıt üst bilgileri:

Parametre Value
Operation-Location İşlemin durumunu almak için kaynağa bağlanın. Örneğin, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kod: 400 Hatalı istek. Sil, bu SaaS aboneliği için listede yok allowedCustomerOperations .

Kod: 403 Yasak. Yetkilendirme belirteci geçersiz, süresi dolmuş veya kullanılamıyor.

Bu hata genellikle SaaS kaydını doğru bir şekilde gerçekleştirmeme belirtisidir.

Kod: 404 Bulunamadı. ile subscriptionId SaaS aboneliği bulunamadı.

Kod: 409

Bekleyen işlemler nedeniyle abonelik kilitlendiğinden silme işlemi tamamlanamıyor.

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

Sonraki adımlar