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

مقالة
05/11/2022
قراءة خلال 20 دقائق

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

حل اشتراك تم شراؤه

تمكن نقطة نهاية الحل الناشر من استبدال الرمز المميز لتعريف الشراء من السوق التجارية (يشار إليه باسم الرمز المميز في تم شراؤه ولكن لم يتم تنشيطه بعد) إلى معرف اشتراك SaaS الذي تم شراؤه باستمرار وتفاصيله.

عند إعادة توجيه عميل إلى عنوان URL للصفحة المقصودة للشريك، يتم تمرير الرمز المميز لتعريف العميل كمعلمة الرمز المميز في مكالمة عنوان URL هذه. من المتوقع أن يستخدم الشريك هذا الرمز المميز ويقدم طلبا لحله. تحتوي استجابة واجهة برمجة تطبيقات Resolve على معرف اشتراك SaaS وتفاصيل أخرى لتحديد عملية الشراء بشكل فريد. عادة ما يكون الرمز المميز المقدم مع مكالمة عنوان URL للصفحة المقصودة صالحا لمدة 24 ساعة. إذا انتهت صلاحية الرمز المميز الذي تتلقاه بالفعل، فإننا نوصي بتقديم الإرشادات التالية للمستخدم النهائي:

"لم نتمكن من تحديد عملية الشراء هذه. يرجى إعادة فتح اشتراك SaaS هذا في مدخل Azure أو في مركز مسؤول Microsoft 365 وتحديد "تكوين الحساب" أو "إدارة الحساب" مرة أخرى.

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

منصب `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

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

المعلمة	القيمة
`ApiVersion`	استخدم 2018-08-31.

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

المعلمة	القيمة
`content-type`	`application/json`
`x-ms-requestid`	قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
`x-ms-correlationid`	قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة.
`authorization`	رمز وصول فريد يحدد الناشر الذي يجري مكالمة واجهة برمجة التطبيقات هذه. التنسيق هو عندما يتم `"Bearer <accessaccess_token>"` استرداد قيمة الرمز المميز من قبل الناشر كما هو موضح في الحصول على رمز مميز استنادا إلى تطبيق Azure AD.
`x-ms-marketplace-token`	معلمة الرمز المميز لتحديد هوية الشراء لحلها. يتم تمرير الرمز المميز في مكالمة عنوان URL للصفحة المقصودة عند إعادة توجيه العميل إلى موقع الويب الخاص بشريك SaaS (على سبيل المثال: `https://contoso.com/signup?token=<token><authorization_token>`). لاحظ أن قيمة الرمز المميز التي يتم ترميزها هي جزء من عنوان URL للصفحة المقصودة، لذلك يجب فك تشفيرها قبل استخدامها كمعلمة في استدعاء واجهة برمجة التطبيقات هذا. في ما يلي مثال على سلسلة مشفرة في عنوان URL: `contoso.com/signup?token=ab%2Bcd%2Fef`، حيث الرمز المميز`ab%2Bcd%2Fef`. نفس الرمز المميز الذي تم فك تشفيره سيكون: `Ab+cd/ef`

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

الرمز: 200 إرجاع معرفات اشتراك SaaS الفريدة بناء على x-ms-marketplace-token المقدمة.

مثال على نص الاستجابة:

{
  "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>",
      "pid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "pid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z",
      "endDate": "2022-04-06T00:00:00Z"
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00",
      "quantity": 5,
    "sessionMode": "None"
  }
}

الرمز: 400 طلب سيء. x-ms-marketplace-token مفقود أو مشوه أو غير صالح أو منتهي الصلاحية.

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

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

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

تنشيط اشتراك

بعد تكوين حساب SaaS لمستخدم نهائي، يجب على الناشر الاتصال بواجهة برمجة تطبيقات تنشيط الاشتراك على جانب Microsoft. لن تتم فوترة العميل ما لم تنجح مكالمة واجهة برمجة التطبيقات هذه.

منصب `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?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.

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

{  // needed for validation of the activation request
  "planId": "gold", // purchased plan, cannot be empty
  "quantity": "3" // purchased number of seats, can be empty if plan is not per seat
}

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

الرمز: 200 تم وضع علامة على الاشتراك على أنه مشترك على جانب Microsoft.

لا توجد هيئة استجابة لهذه الدعوة.

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

planId غير موجود في حمولة الطلب.
planId في الطلب الحمولة الصافية لا تتطابق مع تلك التي تم شراؤها.
quantity في طلب الحمولة الصافية لا تتطابق مع الحمولة التي تم شراؤها
اشتراك SaaS في حالة اشتراك أو تعليق .

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

الرمز: 404 غير موجود. اشتراك SaaS في حالة غير مشترك .

الحصول على قائمة بجميع الاشتراكات

تسترد واجهة برمجة التطبيقات هذه قائمة بجميع اشتراكات SaaS المشتراة لجميع العروض التي ينشرها الناشر في السوق التجارية. سيتم إرجاع اشتراكات SaaS في جميع الحالات الممكنة. يتم أيضا إرجاع اشتراكات SaaS غير المشتركة لأنه لا يتم حذف هذه المعلومات على جانب Microsoft.

تعرض واجهة برمجة التطبيقات نتائج مرقمة بمعدل 100 لكل صفحة.

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

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

المعلمة	القيمة
`ApiVersion`	استخدم 2018-08-31.
`continuationToken`	معلمة اختيارية. لاسترداد الصفحة الأولى من النتائج، اتركها فارغة. استخدم القيمة التي تم إرجاعها في `@nextLink` المعلمة لاسترداد الصفحة التالية.

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

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

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

الرمز: 200 إرجاع قائمة بجميع الاشتراكات الحالية لجميع العروض التي قدمها هذا الناشر، استنادا إلى الرمز المميز لتفويض الناشر.

مثال على نص الاستجابة:

{
  "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, will be 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 relevant only for Active and Suspended subscriptions.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew will happen the next day. This field is relevant only for Active and Suspended subscriptions.
        "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 will always be "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>",
        "pid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "pid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31",
        "endDate": "2020-04-30",
        "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.
}

إذا لم يتم العثور على اشتراكات SaaS المشتراة لهذا الناشر، إرجاع نص الاستجابة الفارغ.

الرمز : 403 ممنوع. الرمز المميز للتفويض غير متوفر أو غير صالح أو منتهي الصلاحية.

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

احصل على اشتراك

تسترد واجهة برمجة التطبيقات هذه اشتراكا محددا تم شراؤه في SaaS لعرض SaaS ينشره الناشر في السوق التجارية. استخدم هذه المكالمة للحصول على جميع المعلومات المتاحة لاشتراك SaaS معين بواسطة معرفه بدلا من الاتصال بواجهة برمجة التطبيقات المستخدمة للحصول على قائمة بجميع الاشتراكات.

حصل `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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 بناء على ما subscriptionId تم توفيره.

مثال على نص الاستجابة:

{
  "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, will be 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 will always be "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",
  "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 relevant only for Active and Suspended subscriptions.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew will happen the next day. This field is relevant only for Active and Suspended subscriptions.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

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

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

قائمة الخطط المتاحة

تسترد واجهة برمجة التطبيقات هذه جميع الخطط لعرض SaaS الذي subscriptionId تم تحديده من خلال عملية شراء محددة لهذا العرض. استخدم هذه الدعوة للحصول على قائمة بجميع الخطط الخاصة والعامة التي يمكن للمستفيد من اشتراك SaaS تحديثها للاشتراك. ستكون الخطط التي تم إرجاعها متاحة في نفس المنطقة الجغرافية مثل الخطة التي تم شراؤها بالفعل.

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

حصل `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?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 الحالي بما في ذلك الاشتراك الذي تم شراؤه بالفعل.

مثال على نص الاستجابة:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "Private platinum plan for Contoso", // display name of the plan as it appears in the marketplace
      "isPrivate": true //true or false
      "description": "plan description",
          "minQuantity": 5,
          "maxQuantity": 100,
          "hasFreeTrials": false,
          "isPricePerSeat": true,
          "isStopSell": false,
          "market": "US",
    },
    {
      "planId": "gold",
      "displayName": "Gold plan for Contoso",
      "isPrivate": false //true or false,
      "description": "gold plan details.",
          "minQuantity": 1,
          "maxQuantity": 5,
          "hasFreeTrials": false,
          "isPricePerSeat": true,
          "isStopSell": false,
          "market": "US",
    }
  ]
}

إذا subscriptionId لم يتم العثور عليها، يتم إرجاع جسم الاستجابة الفارغ.

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

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

تغيير الخطة على الاشتراك

استخدم واجهة برمجة التطبيقات هذه لتحديث الخطة الحالية التي تم شراؤها لاشتراك SaaS إلى خطة جديدة (عامة أو خاصة). يجب على الناشر استدعاء واجهة برمجة التطبيقات هذه عند تغيير خطة على جانب الناشر لاشتراك SaaS تم شراؤه في السوق التجارية.

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

رقع `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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.

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

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

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

الرمز: 202 تم قبول طلب تغيير الخطة والتعامل معه بشكل غير متزامن. من المتوقع أن يقوم الشريك باستطلاع عنوان URL الخاص بموقع العملية لتحديد نجاح أو فشل طلب خطة التغيير. يجب إجراء الاقتراع كل عدة ثوان حتى يتم استلام الحالة النهائية للفشل أو النجاح أو التعارض للعملية. يجب إرجاع حالة التشغيل النهائية بسرعة ، ولكن يمكن أن تستغرق عدة دقائق في بعض الحالات.

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

رؤوس الاستجابة:

المعلمة	القيمة
`Operation-Location`	عنوان URL للحصول على حالة العملية. على سبيل المثال، ⁧`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`⁩.

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

الخطة الجديدة غير موجودة أو غير متوفرة لاشتراك SaaS المحدد هذا.
الخطة الجديدة هي نفسها الخطة الحالية.
حالة اشتراك SaaS غير مشترك.
لا يتم تضمين عملية التحديث لاشتراك SaaS في allowedCustomerOperations.

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

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

ملاحظة

يمكن تغيير الخطة أو كمية المقاعد في وقت واحد ، وليس كليهما.

ملاحظة

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

تغيير كمية المقاعد في اشتراك SaaS

استخدم واجهة برمجة التطبيقات هذه لتحديث (زيادة أو نقصان) كمية المقاعد المشتراة لاشتراك SaaS. يجب على الناشر استدعاء واجهة برمجة التطبيقات هذه عند تغيير عدد المقاعد من جانب الناشر لاشتراك SaaS الذي تم إنشاؤه في السوق التجارية.

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

رقع `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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.

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

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

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

الرمز: 202 تم قبول طلب تغيير الكمية والتعامل معه بشكل غير متزامن. من المتوقع أن يقوم الشريك باستطلاع عنوان URL الخاص بموقع العملية لتحديد نجاح أو فشل طلب كمية التغيير. يجب إجراء الاقتراع كل عدة ثوان حتى يتم استلام الحالة النهائية للفشل أو النجاح أو التعارض للعملية. يجب إرجاع حالة التشغيل النهائية بسرعة ولكن يمكن أن تستغرق عدة دقائق في بعض الحالات.

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

رؤوس الاستجابة:

المعلمة	القيمة
`Operation-Location`	الارتباط بمورد للحصول على حالة العملية. على سبيل المثال، ⁧`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`⁩.

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

الكمية الجديدة أكبر أو أقل من حد الخطة الحالي.
الكمية الجديدة مفقودة.
الكمية الجديدة هي نفسها الكمية الحالية.
حالة اشتراك SaaS غير مشترك.
لا يتم تضمين عملية التحديث لاشتراك SaaS في allowedCustomerOperations.

الرمز : 403 ممنوع. الرمز المميز للتفويض غير صالح أو منتهي الصلاحية أو لم يتم توفيره. يحاول الطلب الوصول إلى اشتراك لا ينتمي إلى الناشر الحالي.

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

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

ملاحظة

يمكن تغيير الخطة أو الكمية فقط في وقت واحد ، وليس كليهما.

ملاحظة

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

إلغاء الاشتراك

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

إذا قرر الناشر تنفيذ إلغاء اشتراك SaaS تم شراؤه في السوق التجارية من جانب الناشر ، فيجب عليه استدعاء واجهة برمجة التطبيقات هذه. بعد الانتهاء من هذه المكالمة، ستصبح حالة الاشتراك غير مشترك على جانب Microsoft.

لن تتم فوترة العميل إذا تم إلغاء الاشتراك في غضون 72 ساعة من الشراء.

ستتم فوترة العميل إذا تم إلغاء الاشتراك بعد فترة السماح السابقة. سيفقد العميل إمكانية الوصول إلى اشتراك SaaS على جانب Microsoft مباشرة بعد الإلغاء.

حذف `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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.

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

الرمز: 202 تم قبول طلب إلغاء الاشتراك والتعامل معه بشكل غير متزامن. من المتوقع أن يقوم الشريك باستطلاع عنوان URL الخاص بموقع العملية لتحديد نجاح أو فشل هذا الطلب. يجب إجراء الاقتراع كل عدة ثوان حتى يتم استلام الحالة النهائية للفشل أو النجاح أو التعارض للعملية. يجب إرجاع حالة التشغيل النهائية بسرعة ولكن يمكن أن تستغرق عدة دقائق في بعض الحالات.

سيحصل الشريك أيضا على إشعار webhook عند اكتمال الإجراء بنجاح على جانب السوق التجاري. عندها فقط يجب على الناشر إلغاء الاشتراك من جانب الناشر.

رؤوس الاستجابة:

المعلمة	القيمة
`Operation-Location`	الارتباط بمورد للحصول على حالة العملية. على سبيل المثال، ⁧`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`⁩.

الرمز: 400 طلب سيء. الحذف ليس في allowedCustomerOperations القائمة لاشتراك SaaS هذا.

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

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

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

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

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

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

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

هل هذه الصفحة مفيدة؟

حل اشتراك تم شراؤه

منصب https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

تنشيط اشتراك

منصب https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

الحصول على قائمة بجميع الاشتراكات

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

احصل على اشتراك

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

قائمة الخطط المتاحة

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

تغيير الخطة على الاشتراك

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

تغيير كمية المقاعد في اشتراك SaaS

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

إلغاء الاشتراك

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

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

منصب `https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

منصب `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

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

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

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

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

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

حذف `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`