واجهات برمجة تطبيقات الفوترة المقننة في السوق
يجب استخدام واجهات برمجة تطبيقات الفوترة المدفوعة عندما ينشئ الناشر أبعاد قياس مخصصة لعرض يتم نشره في مركز الشركاء. يلزم التكامل مع واجهات برمجة تطبيقات الفوترة المقننة لأي عرض تم شراؤه يحتوي على خطة واحدة أو أكثر ذات أبعاد مخصصة لإصدار أحداث الاستخدام.
هام
يجب عليك تتبع الاستخدام في التعليمات البرمجية الخاصة بك وإرسال أحداث الاستخدام فقط إلى Microsoft للاستخدام الذي يزيد عن الرسوم الأساسية.
لمزيد من المعلومات حول إنشاء أبعاد قياس مخصصة ل SaaS، راجع الفوترة المقننة SaaS.
لمزيد من المعلومات حول إنشاء أبعاد قياس مخصصة لعرض تطبيق Azure باستخدام خطة تطبيق مدارة، راجع تكوين تفاصيل إعداد عرض تطبيق Azure.
فرض TLS 1.2 ملاحظة
يتم فرض إصدار TLS 1.2 كإصدار الحد الأدنى لاتصالات HTTPS. تأكد من استخدام إصدار TLS هذا في التعليمات البرمجية الخاصة بك. تم إهمال الإصدار 1.0 و1.1 من TLS وسيتم رفض محاولات الاتصال.
حدث استخدام واحد للفوترة المقننة
يجب أن يتصل الناشر بواجهة برمجة تطبيقات حدث الاستخدام لإصدار أحداث استخدام مقابل مورد نشط (مشترك) للخطة التي اشتراها العميل المحدد. يصدر حدث الاستخدام بشكل منفصل لكل بعد مخصص للخطة التي يحددها الناشر عند نشر العرض.
يمكن إصدار حدث استخدام واحد فقط لكل ساعة من يوم التقويم لكل مورد. إذا تم استهلاك أكثر من وحدة واحدة في ساعة واحدة ، فقم بتجميع جميع الوحدات المستهلكة في الساعة ثم انبعث منها في حدث واحد. لا يمكن إصدار أحداث الاستخدام إلا خلال ال 24 ساعة الماضية. إذا قمت بإصدار حدث استخدام في أي وقت بين الساعة 8:00 و 8:59:59 (وتم قبوله) وأرسلت حدثا إضافيا لنفس اليوم بين الساعة 8:00 و 8:59:59 ، رفضه كنسخة مكررة.
المنشور: https://marketplaceapi.microsoft.com/api/usageEvent?api-version=<ApiVersion>
معلمات الاستعلام:
| المعلمة | التوصية |
|---|---|
ApiVersion |
استخدم 2018-08-31. |
رؤوس الطلبات:
| نوع المحتوى | استخدم application/json |
|---|---|
x-ms-requestid |
قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
x-ms-correlationid |
قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
authorization |
رمز وصول فريد يحدد مورد البرامج المستقل الذي يقوم بإجراء استدعاء واجهة برمجة التطبيقات هذا. التنسيق هو عندما يتم استرداد قيمة الرمز المميز من قبل الناشر كما هو "Bearer <access_token>" موضح ل
|
طلب مثال على نص الرسالة:
{
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
}
ملاحظة
resourceId له معنى مختلف لتطبيق SaaS وللتطبيق المدار الذي ينبعث منه مقياس مخصص.
بالنسبة لخطط التطبيقات المدارة لتطبيق Azure، فإن resourceId التطبيق المدار هو التطبيق resource group Idالمدار . يمكن العثور على مثال على البرنامج النصي لجلبه في استخدام الرمز المميز للهويات المدارة بواسطة Azure.
بالنسبة لعروض SaaS ، فإن resourceId معرف اشتراك SaaS. لمزيد من التفاصيل حول اشتراكات SaaS، راجع قائمة الاشتراكات.
الاستجابات
رمز المنتج: 200
"موافق". تم قبول انبعاثات الاستخدام وتسجيلها على جانب Microsoft لمزيد من المعالجة والفوترة.
مثال على حمولة الاستجابة:
{
"usageEventId": <guid>, // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // this is the only value in case of single usage event
"messageTime": "2020-01-12T13:19:35.3458658Z", // time in UTC this event was accepted
"resourceId": <guid>, // unique identifier of the resource against which usage is emitted. For SaaS it's the subscriptionId.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14", // time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
}
رمز المنتج: 400
طلب سيء.
- بيانات الطلب المفقودة أو غير الصالحة المقدمة.
effectiveStartTimeأكثر من 24 ساعة في الماضي. انتهت صلاحية الحدث.- اشتراك SaaS ليس في حالة اشتراك.
مثال على حمولة الاستجابة:
{
"message": "One or more errors have occurred.",
"target": "usageEventRequest",
"details": [
{
"message": "The resourceId is required.",
"target": "ResourceId",
"code": "BadArgument"
}
],
"code": "BadArgument"
}
رمز المنتج: 403
ممنوع. لم يتم توفير الرمز المميز للتخويل أو أنه غير صالح أو منتهي الصلاحية. أو يحاول الطلب الوصول إلى اشتراك لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء الرمز المميز للتفويض.
رمز المنتج: 409
تعارض. تم بالفعل الإبلاغ عن حدث استخدام بنجاح لمعرف المورد المحدد وتاريخ الاستخدام الفعلي والساعة.
مثال على حمولة الاستجابة:
{
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>", //unique identifier associated with the usage event in Microsoft records
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid>", //unique identifier of the resource against which usage is emitted.
"quantity": 1.0,
"dimension": "dim1",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "plan1"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
}
حدث استخدام دفعة الفوترة المقننة
تتيح لك واجهة برمجة تطبيقات حدث الاستخدام الدفعي إصدار أحداث استخدام لأكثر من مورد تم شراؤه في وقت واحد. كما يسمح لك بإصدار العديد من أحداث الاستخدام لنفس المورد طالما أنها لساعات تقويمية مختلفة. الحد الأقصى لعدد الأحداث في دفعة واحدة هو 25.
منصب:https://marketplaceapi.microsoft.com/api/batchUsageEvent?api-version=<ApiVersion>
معلمات الاستعلام:
| المعلمة | التوصية |
|---|---|
ApiVersion |
استخدم 2018-08-31. |
رؤوس الطلبات:
| نوع المحتوى | استخدم application/json |
|---|---|
x-ms-requestid |
قيمة سلسلة فريدة لتتبع الطلب من العميل، ويفضل أن يكون GUID. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
x-ms-correlationid |
قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
authorization |
رمز وصول فريد يحدد مورد البرامج المستقل الذي يقوم بإجراء استدعاء واجهة برمجة التطبيقات هذا. التنسيق هو عندما يتم استرداد قيمة الرمز المميز من قبل الناشر كما هو Bearer <access_token> موضح ل
|
ملاحظة
في نص الطلب، يكون لمعرف المورد معاني مختلفة لتطبيق SaaS وتطبيق Azure المدار الذي ينبعث منه مقياس مخصص. معرف المورد لتطبيق SaaS هو resourceID. معرف المورد لخطط التطبيقات المدارة لتطبيق Azure هو resourceUri.
بالنسبة لعروض SaaS ، فإن resourceId معرف اشتراك SaaS. لمزيد من التفاصيل حول اشتراكات SaaS، راجع قائمة الاشتراكات.
طلب مثال على النص الأساسي لتطبيقات SaaS:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceId": "<guid1>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
بالنسبة لخطط التطبيقات المدارة لتطبيق Azure، فإن resourceUri التطبيق المدار هو التطبيق resource group Idالمدار . يمكن العثور على مثال على البرنامج النصي لجلبه في استخدام الرمز المميز للهويات المدارة بواسطة Azure.
مثال على نص الطلب للتطبيقات المدارة بواسطة تطبيق Azure:
{
"request": [ // list of usage events for the same or different resources of the publisher
{ // first event
"resourceUri": "<fullyqualifiedname>", // Unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // how many units were consumed for the date and hour specified in effectiveStartTime, must be greater than 0 or a double integer
"dimension": "dim1", //Custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",//Time in UTC when the usage event occurred, from now and until 24 hours back
"planId": "plan1", // id of the plan purchased for the offer
},
{ // next event
"resourceId": "<guid2>",
"quantity": 39.0,
"dimension": "email",
"effectiveStartTime": "2018-11-01T23:33:10
"planId": "gold", // id of the plan purchased for the offer
}
]
}
الاستجابات
رمز المنتج: 200
"موافق". تم قبول انبعاث استخدام الدفعات وتسجيله على جانب Microsoft لمزيد من المعالجة والفوترة. يتم إرجاع قائمة الاستجابة مع حالة كل حدث فردي في الدفعة. يجب عليك التكرار من خلال حمولة الاستجابة لفهم الردود لكل حدث استخدام فردي يتم إرساله كجزء من حدث الدفعة.
مثال على حمولة الاستجابة:
{
"count": 2, // number of records in the response
"result": [
{ // first response
"usageEventId": "<guid>", // unique identifier associated with the usage event in Microsoft records
"status": "Accepted" // see list of possible statuses below,
"messageTime": "2020-01-12T13:19:35.3458658Z", // Time in UTC this event was accepted by Microsoft,
"resourceId": "<guid1>", // unique identifier of the resource against which usage is emitted.
"quantity": 5.0, // amount of emitted units as recorded by Microsoft
"dimension": "dim1", // custom dimension identifier
"effectiveStartTime": "2018-12-01T08:30:14",// time in UTC when the usage event occurred, as sent by the ISV
"planId": "plan1", // id of the plan purchased for the offer
},
{ // second response
"status": "Duplicate",
"messageTime": "0001-01-01T00:00:00",
"error": {
"additionalInfo": {
"acceptedMessage": {
"usageEventId": "<guid>",
"status": "Duplicate",
"messageTime": "2020-01-12T13:19:35.3458658Z",
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
},
"message": "This usage event already exist.",
"code": "Conflict"
},
"resourceId": "<guid2>",
"quantity": 1.0,
"dimension": "email",
"effectiveStartTime": "2020-01-12T11:03:28.14Z",
"planId": "gold"
}
]
}
وصف رمز الحالة المشار إليه في BatchUsageEvent استجابة واجهة برمجة التطبيقات:
| كود الحالة | الوصف |
|---|---|
Accepted |
قبلت. |
Expired |
استخدام منتهي الصلاحية. |
Duplicate |
الاستخدام المكرر المقدم. |
Error |
رمز الخطأ. |
ResourceNotFound |
مورد الاستخدام المقدم غير صالح. |
ResourceNotAuthorized |
أنت غير مخول بتوفير الاستخدام لهذا المورد. |
ResourceNotActive |
تم تعليق المورد أو لم يتم تنشيطه مطلقا. |
InvalidDimension |
البعد الذي تم تمرير الاستخدام من أجله غير صالح لهذا العرض / الخطة. |
InvalidQuantity |
الكمية التي تم تمريرها أقل أو تساوي 0. |
BadArgument |
الإدخال مفقود أو مشوه. |
رمز المنتج: 400
طلب سيء. احتوت الدفعة على أكثر من 25 حدثا للاستخدام.
رمز المنتج: 403
ممنوع. لم يتم توفير الرمز المميز للتخويل أو أنه غير صالح أو منتهي الصلاحية. أو يحاول الطلب الوصول إلى اشتراك لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء الرمز المميز للتفويض.
الفوترة المقننة استرداد أحداث الاستخدام
يمكنك الاتصال بواجهة برمجة تطبيقات أحداث الاستخدام للحصول على قائمة بأحداث الاستخدام. يمكن لموردي البرامج المستقلين استخدام واجهة برمجة التطبيقات هذه للاطلاع على أحداث الاستخدام التي تم نشرها لفترة زمنية معينة قابلة للتكوين والحالة التي تكون فيها هذه الأحداث عند نقطة استدعاء واجهة برمجة التطبيقات.
حصل: https://marketplaceapi.microsoft.com/api/usageEvents
معلمات الاستعلام:
| المعلمة | التوصية |
|---|---|
| ApiVersion | استخدم 2018-08-31. |
| الاستخدامتاريخ البدء | DateTime بتنسيق ISO8601. على سبيل المثال ، 2020-12-03T15: 00 أو 2020-12-03 |
| تاريخ انتهاء الاستخدام (اختياري) | DateTime بتنسيق ISO8601. الافتراضي = التاريخ الحالي |
| معرف العرض (اختياري) | الافتراضي = كل ما هو متاح |
| planId (اختياري) | الافتراضي = كل ما هو متاح |
| البعد (اختياري) | الافتراضي = كل ما هو متاح |
| azureSubscriptionId (اختياري) | الافتراضي = كل ما هو متاح |
| reconStatus (اختياري) | الافتراضي = كل ما هو متاح |
القيم المحتملة ل reconStatus:
| إعادة الحالة | الوصف |
|---|---|
| تم الإرسال | لم تتم معالجتها بعد بواسطة PC Analytics |
| مقبول | متطابقة مع تحليلات الكمبيوتر الشخصي |
| مرفوض وغير موافق عليه | مرفوض في خط الأنابيب. اتصل بدعم Microsoft للتحقيق في السبب. |
| عدم تطابق | كميات MarketplaceAPI وتحليلات مركز الشركاء كلاهما غير صفرية، ولكن غير متطابقة |
| رؤوس الاختبار | الاشتراك مدرج مع رؤوس الاختبار، وبالتالي ليس في PC Analytics |
| دراي رن | تم الإرسال باستخدام SessionMode = DryRun ، وبالتالي ليس في جهاز الكمبيوتر |
رؤوس الطلبات:
| نوع المحتوى | استخدام التطبيق / json |
|---|---|
| x-ms-requestid | قيمة سلسلة فريدة (يفضل أن تكون GUID)، لتتبع الطلب من العميل. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
| x-ms-correlationid | قيمة سلسلة فريدة للتشغيل على العميل. تربط هذه المعلمة جميع الأحداث من تشغيل العميل بالأحداث الموجودة على جانب الخادم. إذا لم يتم توفير هذه القيمة، إنشاء قيمة وتوفيرها في رؤوس الاستجابة. |
| التفويض | رمز وصول فريد يحدد مورد البرامج المستقل الذي يقوم بإجراء استدعاء واجهة برمجة التطبيقات هذا. التنسيق هو عندما يتم Bearer <access_token> استرداد قيمة الرمز المميز من قبل الناشر. لمزيد من المعلومات، انظر:
|
الاستجابات
أمثلة على حمولة الاستجابة:
قبلت*
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Accepted",
"submittedQuantity": 17.0,
"processedQuantity": 17.0,
"submittedCount": 17
}
]
تم الإرسال
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Submitted",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
عدم تطابق
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "Silver",
"offerId": "mycooloffer",
"offerName": "My Cool Offer",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Mismatch",
"submittedQuantity": 17.0,
"processedQuantity": 16.0,
"submittedCount": 17
}
]
مرفوض وغير موافق عليه
[
{
"usageDate": "2020-11-30T00:00:00Z",
"usageResourceId": "11111111-2222-3333-4444-555555555555",
"dimension": "tokens",
"planId": "silver",
"planName": "",
"offerId": "mycooloffer",
"offerName": "",
"offerType": "SaaS",
"azureSubscriptionId": "12345678-9012-3456-7890-123456789012",
"reconStatus": "Rejected",
"submittedQuantity": 17.0,
"processedQuantity": 0.0,
"submittedCount": 17
}
]
تعليمات الحالة البرمجية
الرمز : 403 ممنوع. لم يتم توفير الرمز المميز للتخويل أو أنه غير صالح أو منتهي الصلاحية. أو يحاول الطلب الوصول إلى اشتراك لعرض تم نشره باستخدام معرف تطبيق Azure AD مختلف عن المعرف المستخدم لإنشاء الرمز المميز للتفويض.
تطوير واختبار أفضل الممارسات
لاختبار انبعاث العداد المخصص ، قم بتنفيذ التكامل مع واجهة برمجة تطبيقات القياس ، وقم بإنشاء خطة لعرض SaaS المنشور الخاص بك بأبعاد مخصصة محددة فيه بسعر صفري لكل وحدة. وانشر هذا العرض كمعاينة حتى يتمكن المستخدمون المحدودون فقط من الوصول إلى التكامل واختباره.
يمكنك أيضا استخدام خطة خاصة لعرض مباشر حالي للحد من الوصول إلى هذه الخطة أثناء الاختبار لجمهور محدود.
الحصول على الدعم
اتبع الإرشادات الواردة في دعم برنامج السوق التجاري في "مركز الشركاء" لفهم خيارات دعم الناشرين وفتح تذكرة دعم مع Microsoft.
الخطوات التالية
لمزيد من المعلومات حول واجهات برمجة تطبيقات خدمة القياس، راجع الأسئلة المتداولة حول واجهات برمجة تطبيقات خدمة قياس Marketplace.