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

  • Makale

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ı aracılığıyla gelen istekleri yanıtlamak için yararlıdır. Bu, aşağıdaki API'leri kullanarak web kancası işlemine Başarılı veya Başarısız 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) Yenileme, Askıya Alma ve Abonelikten Çıkma olaylarında hiçbir eyleme gerek yoktur çünkü bunlar yalnızca bildirim olaylarıdır.

Bekleyen işlemleri listeleme

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

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

Sorgu parametreleri:

Parametre Değer
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 Değer
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz bir 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 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>" belirteç değerinin yayımcı tarafından Azure AD uygulamasını temel alan belirteç alma bölümünde açıklandığı gibi 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 Azure AD uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Bu hata genellikle SaaS kaydının doğru şekilde gerçekleştirilmediğine ilişkin bir belirtidir.

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: Aboneliği kaldırma, ChangePlan veya ChangeQuantity.

operationId Bu API çağrısı için operation-location tarafından döndürülen değerden, bekleyen İşlemLER API'sini alma ç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 Değer
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 Değer
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz bir 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 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>" belirteç değerinin yayımcı tarafından Azure AD uygulamasını temel alan belirteç alma bölümünde açıklandığı gibi 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 Azure AD uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Bu hata genellikle SaaS kaydının doğru şekilde gerçekleştirilmediğine ilişkin bir belirtidir.

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'sini alma ç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 Değer
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 Değer
content-type application/json
x-ms-requestid İstemciden gelen isteği izlemek için benzersiz bir 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 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>" belirteç değerinin yayımcı tarafından Azure AD uygulamasını temel alan belirteç alma bölümünde açıklandığı gibi 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 koltuk 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 Azure AD uygulama kimliğiyle yayımlanan bir teklif için SaaS aboneliğine erişmeye çalışır.

Bu hata genellikle SaaS kaydının doğru şekilde gerçekleştirilmediğine ilişkin bir belirtidir.

Kod: 404 Bulunamadı.

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

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

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

Sonraki adımlar