Microsoft ticari marketinde SaaS gerçekleştirme işlemleri API'leri v2

  • Makale

Not

SaaS gerçekleştirme İşlemleri API'lerini çağırabilmek için doğru kaynak kimliğini kullanarak bir yayımcının yetkilendirme belirtecini oluşturmanız gerekir. Yayımcının yetkilendirme belirtecini almayı öğrenin

Bu makalede SaaS gerçekleştirme işlemleri API'lerinin 2. sürümü açıklanmaktadır.

İşlemler, ChangePlan, ChangeQuantity ve Reinstate eylemlerinin bir parçası olarak web kancası üzerinden gelen tüm isteklere yanıt vermek için kullanışlıdır. Bu, aşağıdaki API'leri kullanarak web kancası işlemine Başarılı veya Başarısız olarak düzeltme eki ekleyerek bir isteği kabul etme veya reddetme fırsatı sağlar.

Bu yalnızca ACK gerektiren ChangePlan, ChangeQuantity ve Reinstate gibi web kancası olayları için geçerlidir. Bağımsız yazılım satıcısının (ISV) yalnızca bildirim olayları olduğundan Yenileme, Askıya Alma ve Abonelikten Çıkma olaylarında herhangi bir eyleme gerek yoktur.

Bekleyen işlemleri listeleme

Belirtilen SaaS aboneliği için bekleyen işlemlerin listesini alın. Yayımcı, İşlem Düzeltme Eki API'sini çağırarak döndürülen işlemleri kabul etmelidir.

Al https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?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 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 Belirtilen SaaS aboneliğinde bekleyen işlemleri döndürür.

Yanıt yükü örneği:

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Bekleyen işlem yoksa boş json döndürür.

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

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.

İşlem durumunu alma

Bu API yayımcının belirtilen zaman uyumsuz işlemin durumunu izlemesine olanak tanır: Abonelikten çık, ChangePlan veya ChangeQuantity.

operationId Bu API çağrısı için, Operation-Location tarafından döndürülen değerden, bekleyen İşlemler API çağrısından veya bir web kancası çağrısında alınan parametre değerinden <id> alınabilir.

Al https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId Alınan işlemin benzersiz tanımlayıcısı.

İ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 Belirtilen SaaS işleminin ayrıntılarını alır.

Yanıt yükü örneği:

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

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

  • aboneliği subscriptionId bulunamadı.
  • ile operationId işlemi bulunamadı.

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

İşlemin durumunu güncelleştirme

İşlemin yayımcı tarafında başarılı veya başarısız olduğunu belirtmek üzere bekleyen bir işlemin durumunu güncelleştirmek için bu API'yi kullanın.

operationId Bu API çağrısı için, Operation-Location tarafından döndürülen değerden, bekleyen İşlemler API çağrısından veya bir web kancası çağrısında alınan parametre değerinden <id> alınabilir.

Yama https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId Tamamlanan işlemin benzersiz tanımlayıcısı.

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

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

Yanıt kodları:

Kod: 200 İş ortağı tarafında bir işlemin tamamlanmasını bildiren bir çağrı. Örneğin, bu yanıt yayımcı tarafında yer veya plan değişikliğinin tamamlanmasını işaret edebilir.

Kod: 403

  • Yasak. Yetkilendirme belirteci kullanılamıyor, geçersiz veya süresi dolmuş. İstek, geçerli yayımcıya ait olmayan bir aboneliğe erişmeye çalışabilir.
  • 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ı.

  • aboneliği subscriptionId bulunamadı.
  • ile operationId işlemi bulunamadı.

Kod: 409 Çakışması. Örneğin, daha yeni bir güncelleştirme zaten yerine getiriliyor.

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

İlgili içerik