احصل على مجموعات بيانات صغيرة التكلفة عند الطلب

استخدام واجهة برمجة تطبيقات تفاصيل التكلفة للحصول على بيانات التكلفة الأولية غير المصنفة التي تتوافق مع فاتورة Azure. وتكون واجهة برمجة التطبيقات (API) مفيدة عندما تحتاج مؤسستك إلى حل استرداد بيانات برمجي. ضع في اعتبارك استخدام واجهة برمجة التطبيقات إذا كنت تريد تحليل مجموعات بيانات التكلفة الأصغر من 2 غيغابايت (2 مليون صف) أو أقل. ومع ذلك، يجب استخدام Exports لأحمال عمل استيعاب البيانات المستمرة وتنزيل مجموعات البيانات الأكبر.

إذا كنت ترغب في الحصول على كميات كبيرة من البيانات المصدرة بانتظام، راجع استرداد مجموعات بيانات التكلفة الكبيرة بشكل متكرر من خلال عمليات التصدير.

لمعرفة المزيد حول البيانات في تفاصيل التكلفة (يشار إليها سابقًا باسم تفاصيل الاستخدام)، راجع استيعاب بيانات تفاصيل التكلفة.

يتوفر تقرير تفاصيل التكلفة فقط للعملاء الذين لديهم اتفاقية Enterprise أو اتفاقية عملاء Microsoft. إذا كنت من عملاء MSDN أو الدفع أولا بأول أو Visual Studio، فشاهد الحصول على تفاصيل التكلفة لاشتراك الدفع أولا بأول.

الأذونات

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

إشعار

لا تدعم واجهة برمجة تطبيقات تفاصيل التكلفة مجموعات الإدارة لعملاء EA أو MCA.

لمزيد من المعلومات، راجع:

• نطاقات التحكم في الوصول استناداً إلى الدور في Azure - أذونات الدور لسلوك الميزة
• نطاقات اتفاقية Enterprise - أذونات الدور لسلوك الميزة
• نطاقات اتفاقية عملاء Microsoft - أذونات الدور لسلوك الميزة

أفضل ممارسات واجهة برمجة تطبيقات تفاصيل التكلفة

توصي Microsoft بأفضل الممارسات التالية أثناء استخدام واجهة برمجة تطبيقات تفاصيل التكلفة.

جدولة الطلبات

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

قم بتقسيم طلباتك

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

إذا كانت مجموعة البيانات الخاصة بك تزيد عن 2 جيجابايت (أو ما يقرب من 2 مليون صف) شهريًا، ففكر في استخدام الصادرات كحل أكثر قابلية للتوسع.

زمن الانتقال وحدود الأسعار

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

النطاقات الزمنية لمجموعة البيانات المدعومة

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

مثال طلبات واجهة برمجة تطبيقات تفاصيل التكلفة

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

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

لمعرفة المزيد حول عقد واجهة برمجة التطبيقات، راجع واجهة برمجة تطبيقات تفاصيل التكلفة.

التكلفة الفعلية مقابل التكلفة المستهلكة

للتحكم في ما إذا كنت ترغب في رؤية تقرير تكلفة فعلي أو تقرير تكلفة مطفأ، قم بتغيير القيمة المستخدمة لحقل القياس في نص الطلب الأولي. قيم القياس المتوفرة هي ActualCost أو AmortizedCost.

تعمل التكلفة المستهلكة على تقسيم مشتريات الحجز إلى أجزاء يومية وتوزعها على مدار مدة الحجز. على سبيل المثال، بدلاً من مشاهدة عملية شراء بمقدار 365 دولارًا في 1 يناير، ستشاهد عملية شراء بمقدار 1.00 دولار كل يوم بدءًا من 1 يناير وحتى 31 ديسمبر. بالإضافة إلى الاستهلاك الأساسي، يتم أيضاً إعادة تخصيص هذه التكاليف وربطها باستخدام الموارد المحددة التي استخدمت الحجز. على سبيل المثال، إذا تم تقسيم هذه الرسوم اليومية وقدرها 1.00 دولار بين جهازين ظاهريين، فستشاهد رسمين لليوم مقدار كل منهما 0.50 دولار. إذا لم يتم استخدام جزء من الحجز لهذا اليوم، فسترى رسومًا بقيمة 0.50 دولار مرتبطة بالجهاز الظاهري المطبق ورسومًا أخرى قدرها 0.50 دولار بنوع رسوم UnusedReservation. يمكن رؤية تكاليف الحجز غير المستخدمة فقط عند عرض التكلفة المستهلكة.

بسبب التغيير في كيفية تمثيل التكاليف، من المهم ملاحظة أن التكلفة الفعلية وطرق عرض التكلفة المستهلكة تظهر أرقاما إجمالية مختلفة. بشكل عام، ستنخفض التكلفة الإجمالية للأشهر بمرور الوقت لشراء الحجز عند عرض التكاليف المطفأة. تكلفة الأشهر بعد زيادة شراء الحجز. يتوفر الاستهلاك فقط لعمليات شراء الحجز ولا ينطبق على مشتريات Azure Marketplace حاليًا.

الطلب الأولي لإنشاء تقرير

POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2022-05-01

نص طلب:

فيما يلي مثال لطلب مجموعة بيانات ActualCost لنطاق تاريخ محدد.

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2020-03-01",
    "end": "2020-03-15"
  }
}

يتم توثيق خيارات {scope} المتوفرة لإنشاء URI المناسب في تحديد معرف المورد لنطاق.

فيما يلي الحقول المتوفرة التي يمكنك توفيرها في نص طلب التقرير.

• metric - نوع التقرير المطلوب. يمكن أن يكون إما ActualCost أو AmortizedCost. غير مطلوب. إذا لم يتم تحديد الحقل، يتم تعيين API افتراضيا إلى تقرير ActualCost.
• timePeriod - نطاق التاريخ المطلوب لبياناتك. غير مطلوب. لا يمكن استخدام هذه المعلمة جنبا إلى جنب مع معلمات invoiceId أو billingPeriod. إذا لم يتم توفير معلمة timePeriod أو invoiceId أو billingPeriod في نص الطلب، فترجع واجهة برمجة التطبيقات تكلفة الشهر الحالي.
• invoiceId - الفاتورة المطلوبة لبياناتك. يتم استخدام هذه المعلمة فقط من قبل عملاء اتفاقية عملاء Microsoft. بالإضافة إلى ذلك، لا يمكن استخدامه إلا في نطاق ملف تعريف الفوترة أو العميل. لا يمكن استخدام هذه المعلمة جنبًا إلى جنب مع معلمات billingPeriod أو timePeriod. إذا لم يتم توفير معلمة timePeriod أو invoiceId أو billingPeriod في نص الطلب، فترجع واجهة برمجة التطبيقات تكلفة الشهر الحالي.
• billingPeriod - فترة الفوترة المطلوبة لبياناتك. يتم استخدام هذه المعلمة فقط من قبل عملاء اتفاقية Enterprise. استخدم تنسيق YearMonth. على سبيل المثال 202008. لا يمكن استخدام هذه المعلمة جنبًا إلى جنب مع معلمات invoiceId أو timePeriod. إذا لم يتم توفير معلمة timePeriod أو invoiceId أو billingPeriod في نص الطلب، فترجع واجهة برمجة التطبيقات تكلفة الشهر الحالي.

استجابة واجهة برمجة التطبيقات:

Response Status: 202 – Accepted : يشير إلى قبول الطلب. Location استخدم العنوان للتحقق من الحالة.

عناوين الاستجابة:

Name	نوع	التنسيق	‏‏الوصف
الموقع	السلسلة‬		عنوان URL للتحقق من نتيجة العملية غير المتزامنة.
Retry-After	Integer	Int32	الوقت المتوقع لإنشاء التقرير. انتظر هذه المدة قبل إجراء الاستقصاء مرة أخرى.

التحقق من التقرير وتنزيله

الاستقصاء عن التقرير باستخدام نقطة النهاية المتوفرة location في رأس استجابة واجهة برمجة التطبيقات بعد تقديم طلب لإنشاء تقرير تفاصيل التكلفة. فيما يلي مثال لطلب الاستقصاء.

طلب تقرير التصويت:

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

Response Status 200 – Succeeded: يشير إلى نجاح الطلب.

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/operationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}

فيما يلي ملخص للحولات الرئيسية في استجابة واجهة برمجة التطبيقات:

• manifestVersion - إصدار عقد البيان المستخدم في الاستجابة. في هذا الوقت، يظل إصدار البيان هو نفسه لإصدار واجهة برمجة تطبيقات معين.
• dataFormat - CSV هو تنسيق الملف الوحيد المدعوم الذي توفره واجهة برمجة التطبيقات في هذا الوقت.
• blobCount - يمثل عدد الكائنات الثنائية كبيرة الحجم للبيانات الفردية الموجودة في مجموعة بيانات التقرير. من المهم ملاحظة أن واجهة برمجة التطبيقات هذه قد توفر مجموعة بيانات مقسمة لأكثر من ملف واحد في الاستجابة. تصميم مسارات البيانات الخاصة بك لتكون قادرة على التعامل مع الملفات المقسمة وفقا لذلك. يسمح لك التقسيم بالتمكن من استيعاب مجموعات البيانات الأكبر حجما بسرعة أكبر للمضي قدما.
• byteCount - إجمالي عدد البايت لمجموعة بيانات التقرير عبر جميع الأقسام.
• ضغط البيانات - يتم تعيين الضغط دائما إلى خطأ للإصدار الأول. ومع ذلك، ستدعم واجهة برمجة التطبيقات الضغط في المستقبل.
• requestContext - التكوين الأولي المطلوب للتقرير.
• الكائنات الثنائية كبيرة الحجم - قائمة بملفات n blob التي تشكل التقرير الكامل معا.
  • blobLink - عنوان URL لتنزيل قسم كائن ثنائي كبير الحجم فردي.
  • byteCount - عدد البايت لقسم الكائن الثنائي كبير الحجم الفردي.
• validTill - تاريخ عدم إمكانية الوصول إلى التقرير.

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

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