واجهات برمجة تطبيقات عمليات تنفيذ SaaS v2 في سوق Microsoft التجاري

  • مقالة
  • قراءة خلال 5 دقائق

توضح هذه المقالة الإصدار 2 من واجهات برمجة تطبيقات عمليات تنفيذ SaaS.

قائمة العمليات المعلقة

احصل على قائمة بالعمليات المعلقة لاشتراك SaaS المحدد. يجب على الناشر الإقرار بالعمليات التي تم إرجاعها عن طريق استدعاء واجهة برمجة تطبيقات تصحيح العمليات.

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

معلمات الاستعلام:

المعلمة القيمة
ApiVersion استخدم 2018-08-31.
subscriptionId المعرف الفريد لاشتراك SaaS الذي تم شراؤه. يتم الحصول على هذا المعرف بعد حل الرمز المميز لتفويض السوق التجاري باستخدام واجهة برمجة تطبيقات الحل.

رؤوس الطلبات:

المعلمة القيمة
content-type application/json
x-ms-requestid قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
x-ms-correlationid قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
authorization التنسيق هو عندما يتم "Bearer <access_token>" استرداد قيمة الرمز المميز من قبل الناشر كما هو موضح في الحصول على رمز مميز استنادا إلى تطبيق Azure AD.

رموز الاستجابة:

الرمز: 200 إرجاع العمليات المعلقة على اشتراك SaaS المحدد.

مثال على حمولة الاستجابة:

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

إرجاع json فارغ إذا لم تكن هناك عمليات معلقة.

الرمز: 400 طلب غير صحيح: فشل التحقق من الصحة.

الرمز : 403 ممنوع. الرمز المميز للتفويض غير صالح أو منتهي الصلاحية أو لم يتم توفيره. يحاول الطلب الوصول إلى اشتراك SaaS لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء رمز التفويض.

غالبا ما يكون هذا الخطأ أحد أعراض عدم إجراء تسجيل SaaS بشكل صحيح.

الرمز: 404 غير موجود. لم يتم العثور على اشتراك SaaS مع subscriptionId .

التعليمات البرمجية: 500 خطأ داخلي في الخادم. أعد محاولة استدعاء واجهة برمجة التطبيقات. إذا استمر الخطأ، اتصل بدعم Microsoft.

الحصول على حالة التشغيل

تمكن واجهة برمجة التطبيقات هذه الناشر من تتبع حالة العملية غير المتزامنة المحددة: إلغاء الاشتراك أو ChangePlan أو ChangeQuantity.

يمكن استرداد استدعاء واجهة برمجة التطبيقات هذا من القيمة التي تم operationId إرجاعها بواسطة موقع العملية أو استدعاء واجهة برمجة تطبيقات العمليات المعلقة أو قيمة المعلمة <id> المستلمة في مكالمة webhook.

حصل https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>

معلمات الاستعلام:

المعلمة القيمة
ApiVersion استخدم 2018-08-31.
subscriptionId المعرف الفريد لاشتراك SaaS الذي تم شراؤه. يتم الحصول على هذا المعرف بعد حل الرمز المميز لتفويض السوق التجاري باستخدام واجهة برمجة تطبيقات الحل.
operationId المعرف الفريد للعملية التي يتم استردادها.

رؤوس الطلبات:

المعلمة القيمة
content-type application/json
x-ms-requestid قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
x-ms-correlationid قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
authorization رمز وصول فريد يحدد الناشر الذي يجري مكالمة واجهة برمجة التطبيقات هذه. التنسيق هو عندما يتم "Bearer <access_token>" استرداد قيمة الرمز المميز من قبل الناشر كما هو موضح في الحصول على رمز مميز استنادا إلى تطبيق Azure AD.

رموز الاستجابة:

الرمز: 200 يحصل على تفاصيل لعملية SaaS المحددة.

مثال على حمولة الاستجابة:

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

الرمز : 403 ممنوع. الرمز المميز للتفويض غير صالح أو منتهي الصلاحية أو لم يتم توفيره. يحاول الطلب الوصول إلى اشتراك SaaS لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء رمز التفويض.

غالبا ما يكون هذا الخطأ أحد أعراض عدم إجراء تسجيل SaaS بشكل صحيح.

الرمز: 404 غير موجود.

  • لم يتم العثور على الاشتراك مع subscriptionId .
  • لم يتم العثور على العملية مع operationId .

التعليمات البرمجية: 500 خطأ داخلي في الخادم. أعد محاولة استدعاء واجهة برمجة التطبيقات. إذا استمر الخطأ، اتصل بدعم Microsoft.

تحديث حالة عملية

استخدم واجهة برمجة التطبيقات هذه لتحديث حالة عملية معلقة للإشارة إلى نجاح العملية أو فشلها على جانب الناشر.

يمكن استرداد استدعاء واجهة برمجة التطبيقات هذا من القيمة التي تم operationId إرجاعها بواسطة موقع العملية أو استدعاء واجهة برمجة تطبيقات العمليات المعلقة أو قيمة المعلمة <id> المستلمة في مكالمة webhook.

رقع https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>

معلمات الاستعلام:

المعلمة القيمة
ApiVersion استخدم 2018-08-31.
subscriptionId المعرف الفريد لاشتراك SaaS الذي تم شراؤه. يتم الحصول على هذا المعرف بعد حل الرمز المميز لتفويض السوق التجاري باستخدام واجهة برمجة تطبيقات الحل.
operationId المعرف الفريد للعملية التي يتم إكمالها.

رؤوس الطلبات:

المعلمة القيمة
content-type application/json
x-ms-requestid قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
x-ms-correlationid قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
authorization رمز وصول فريد يحدد الناشر الذي يجري مكالمة واجهة برمجة التطبيقات هذه. التنسيق هو عندما يتم "Bearer <access_token>" استرداد قيمة الرمز المميز من قبل الناشر كما هو موضح في الحصول على رمز مميز استنادا إلى تطبيق Azure AD.

طلب مثال على الحمولة:

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

رموز الاستجابة:

الرمز: 200 مكالمة للإبلاغ عن الانتهاء من عملية على جانب الشريك. على سبيل المثال، يمكن أن تشير هذه الاستجابة إلى اكتمال تغيير المقاعد أو الخطط على جانب الناشر.

رمز المنتج: 403

  • ممنوع. الرمز المميز للتفويض غير متوفر أو غير صالح أو منتهي الصلاحية. قد يحاول الطلب الوصول إلى اشتراك لا ينتمي إلى الناشر الحالي.
  • ممنوع. الرمز المميز للتفويض غير صالح أو منتهي الصلاحية أو لم يتم توفيره. يحاول الطلب الوصول إلى اشتراك SaaS لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء رمز التفويض.

غالبا ما يكون هذا الخطأ أحد أعراض عدم إجراء تسجيل SaaS بشكل صحيح.

الرمز: 404 غير موجود.

  • لم يتم العثور على الاشتراك مع subscriptionId .
  • لم يتم العثور على العملية مع operationId .

الرمز: 409 تعارض. على سبيل المثال، تم بالفعل استيفاء تحديث أحدث.

التعليمات البرمجية: 500 خطأ داخلي في الخادم. أعد محاولة استدعاء واجهة برمجة التطبيقات. إذا استمر الخطأ، اتصل بدعم Microsoft.

الخطوات التالية

راجع واجهات برمجة تطبيقات خدمة قياس السوق التجارية لمزيد من الخيارات لعروض SaaS في السوق التجارية.

مراجعة واستخدام العملاء للغات البرمجة والعينات المختلفة.