إضافة الكائنات الثنائية كبيرة الحجم إلى الكائنات في Azure Digital Twins

مقالة
01/10/2020

هام

تم إصدار إصدار جديد من خدمة Azure Digital Twins. في ضوء قدرات الخدمة الجديدة الموسعة، تم إيقاف خدمة Azure Digital Twins الأصلية (الموضحة في مجموعة الوثائق هذه).

لعرض وثائق الخدمة الجديدة، قم بزيارة وثائق Azure Digital Twins النشطة.

الكائنات الثنائية كبيرة الحجم هي تمثيلات غير منظمة من أنواع الملفات الشائعة، مثل الصور والسجلات. تتعقب الكائنات الثنائية كبيرة الحجم نوع البيانات التي تمثلها باستخدام نوع MIME (على سبيل المثال: "image/jpeg") وبيانات التعريف (الاسم والوصف والنوع وما إلى ذلك).

يدعم Azure Digital Twins إرفاق الكائنات الثنائية كبيرة الحجم بالأجهزة والمساحات والمستخدمين. يمكن أن تمثل الكائنات الثنائية كبيرة الحجم صورة ملف تعريف لمستخدم، وصورة جهاز، وفيديو، وخريطة، ومضغوطة للبرامج الثابتة، وبيانات JSON، وسجل، وما إلى ذلك.

تفترض هذه المقالة بعض الإلمام بالمصادقة على واجهات برمجة تطبيقات Azure Digital Twins Management.

لمعرفة المزيد حول المصادقة باستخدام واجهات برمجة تطبيقات الإدارة، اقرأ المصادقة باستخدام واجهات برمجة تطبيقات Azure Digital Twins.
للمصادقة مع واجهات برمجة تطبيقات الإدارة باستخدام عميل Postman REST، اقرأ كيفية تكوين Postman.

نظرة عامة على تحميل الكائنات الثنائية كبيرة الحجم

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

إشعار

تتطلب الطلبات متعددة الأجزاء عادة ثلاث قطع:

رأس نوع المحتوى:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
ترتيب المحتوى:
- form-data; name="metadata"
محتوى الملف المطلوب تحميله

سيختلف نوع المحتوى والتصرف في المحتوى وفقا لسيناريو الاستخدام.

يمكن إجراء الطلبات متعددة الأقسام برمجيا (من خلال C#)، من خلال عميل REST، أو أداة مثل Postman. قد يكون لأدوات عميل REST مستويات مختلفة من الدعم للطلبات المعقدة متعددة الأقسام. قد تختلف إعدادات التكوين أيضا قليلا من أداة إلى أخرى. تحقق من الأداة الأنسب لاحتياجاتك.

هام

عادة ما تحتوي الطلبات متعددة الأجزاء التي يتم إجراؤها على واجهات برمجة تطبيقات Azure Digital Twins Management على جزأين:

بيانات تعريف Blob (مثل نوع MIME المقترن) التي تم الإعلان عنها بواسطة Content-Type و/أو Content-Disposition
محتويات Blob التي تتضمن المحتويات غير المنظمة لملف ليتم تحميله

لا يلزم أي من الجزأين لطلبات PATCH . كلاهما مطلوب لعمليات POST أو الإنشاء.

تحتوي التعليمات البرمجية لمصدر التشغيل السريع للشغل على أمثلة C# كاملة توضح كيفية إجراء طلبات متعددة الأجزاء مقابل واجهات برمجة تطبيقات Azure Digital Twins Management.

بيانات تعريف Blob

بالإضافة إلى نوع المحتوى والتخلص من المحتوى، يجب أن تحدد طلبات Azure Digital Twins blob متعددة الأقسام نص JSON الصحيح. يعتمد نص JSON المطلوب إرساله على نوع عملية طلب HTTP التي يتم تنفيذها.

مخططات JSON الرئيسية الأربعة هي:

تتوافق بيانات تعريف كائن ثنائي كبير الحجم JSON مع النموذج التالي:

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }

السمة	النوع	‏‏الوصف
معرف الأصل	السلسلة‬	الكيان الأصل لإقران الكائن الثنائي كبير الحجم ب (مسافات أو أجهزة أو مستخدمين)
الاسم	السلسلة‬	اسم مألوف للإنسان للكائن الثنائي كبير الحجم
النوع	السلسلة‬	نوع الكائن الثنائي كبير الحجم - لا يمكن استخدام النوع و typeId
معرف النوع	رقم صحيح	معرف نوع الكائن الثنائي كبير الحجم - لا يمكن استخدام النوع و typeId
النوع الفرعي	السلسلة‬	النوع الفرعي للكائن الثنائي كبير الحجم - لا يمكن استخدام النوع الفرعي ومعرف النوع الفرعي
معرف النوع الفرعي	رقم صحيح	معرف النوع الفرعي للكائن الثنائي كبير الحجم - لا يمكن استخدام النوع الفرعي ومعرف النوع الفرعي
الوصف	السلسلة‬	وصف مخصص للكائن الثنائي كبير الحجم
تقاسم	السلسلة‬	ما إذا كان يمكن مشاركة الكائن الثنائي كبير الحجم - تعداد [`None`، ، `TreeGlobal`]

يتم توفير بيانات تعريف Blob دائما كأول مجموعة مع نوع application/json المحتوى أو كملف .json . يتم توفير بيانات الملف في المجموعة الثانية ويمكن أن تكون من أي نوع MIME مدعوم.

تصف وثائق Swagger مخططات النموذج هذه بالتفصيل الكامل.

تلميح

يتم توفير معاينة التسلل Swagger لإظهار مجموعة ميزات واجهة برمجة التطبيقات. تتم استضافته في docs.westcentralus.azuresmartspaces.net/management/swagger.

يمكنك الوصول إلى وثائق Management API Swagger التي تم إنشاؤها على:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

الاسم	استبدال بـ
YOUR_INSTANCE_NAME	اسم مثيل Azure Digital Twins
YOUR_LOCATION	منطقة الخادم التي تتم استضافة المثيل الخاص بك عليها

تعرف على استخدام الوثائق المرجعية من خلال قراءة كيفية استخدام Swagger.

بيانات استجابة الكائنات الثنائية كبيرة الحجم

تتوافق الكائنات الثنائية كبيرة الحجم التي تم إرجاعها بشكل فردي مع مخطط JSON التالي:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "parentId": "00000000-0000-0000-0000-000000000000",
  "type": "string",
  "subtype": "string",
  "typeId": 0,
  "subtypeId": 0,
  "sharing": "None",
  "description": "string",
  "contentInfos": [
    {
      "type": "string",
      "sizeBytes": 0,
      "mD5": "string",
      "version": "string",
      "lastModifiedUtc": "2019-01-12T00:58:08.689Z",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "fullName": "string",
  "spacePaths": [
    "string"
  ]
}

السمة	النوع	الوصف
معرف	السلسلة‬	المعرف الفريد للكائن الثنائي كبير الحجم
الاسم	السلسلة‬	اسم مألوف للإنسان للكائن الثنائي كبير الحجم
معرف الأصل	السلسلة‬	الكيان الأصل لإقران الكائن الثنائي كبير الحجم ب (مسافات أو أجهزة أو مستخدمين)
النوع	السلسلة‬	نوع الكائن الثنائي كبير الحجم - لا يمكن استخدام النوع و typeId
معرف النوع	رقم صحيح	معرف نوع الكائن الثنائي كبير الحجم - لا يمكن استخدام النوع و typeId
النوع الفرعي	السلسلة‬	النوع الفرعي للكائن الثنائي كبير الحجم - لا يمكن استخدام النوع الفرعي ومعرف النوع الفرعي
معرف النوع الفرعي	رقم صحيح	معرف النوع الفرعي للكائن الثنائي كبير الحجم - لا يمكن استخدام النوع الفرعي ومعرف النوع الفرعي
تقاسم	السلسلة‬	ما إذا كان يمكن مشاركة الكائن الثنائي كبير الحجم - تعداد [`None`، ، `TreeGlobal`]
الوصف	السلسلة‬	وصف مخصص للكائن الثنائي كبير الحجم
معلومات المحتوى	صفيف	تحديد معلومات بيانات التعريف غير المنظمة بما في ذلك الإصدار
الاسم الكامل	السلسلة‬	الاسم الكامل للكائن الثنائي كبير الحجم
ممرات المسافة	السلسلة‬	مسار المسافة

أمثلة على طلب كائن ثنائي كبير الحجم متعدد الأقسام

في الأمثلة أدناه، YOUR_MANAGEMENT_API_URL يشير إلى URI لواجهات برمجة تطبيقات Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

الاسم	استبدال بـ
YOUR_INSTANCE_NAME	اسم مثيل Azure Digital Twins
YOUR_LOCATION	المنطقة التي تتم استضافة المثيل فيها

لتحميل ملف نصي ككائن ثنائي كبير الحجم وربطه بمسافة، قم بإجراء طلب HTTP POST مصادق عليه إلى:

YOUR_MANAGEMENT_API_URL/spaces/blobs

مع النص التالي:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
  "Name": "My First Blob",
  "Type": "Map",
  "SubType": "GenericMap",
  "Description": "A well chosen description",
  "Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain

This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.

--USER_DEFINED_BOUNDARY--

القيمة‬	استبدال بـ
USER_DEFINED_BOUNDARY	اسم حد محتوى متعدد الأحزاب

التعليمات البرمجية التالية هي تطبيق .NET لنفس تحميل الكائن الثنائي كبير الحجم، باستخدام فئة MultipartFormDataContent:

//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");

var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");

//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");

var response = await httpClient.PostAsync("spaces/blobs", multipartContent);

وأخيرا، يمكن لمستخدمي cURL تقديم طلبات نماذج متعددة الأقسام بنفس الطريقة:

curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: multipart/form-data" \
 -F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
 -F "text=PATH_TO_FILE;type=text/plain"

القيمة‬	استبدال بـ
YOUR_TOKEN	رمز OAuth 2.0 المميز الصالح
YOUR_SPACE_ID	معرف المساحة لإقران الكائن الثنائي كبير الحجم
PATH_TO_FILE	المسار إلى الملف النصي

يقوم POST الناجح بإرجاع معرف الكائن الثنائي كبير الحجم الجديد.

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

تصف الأقسام التالية نقاط نهاية واجهة برمجة التطبيقات الأساسية المتعلقة بالكائنات الثنائية كبيرة الحجم ووظائفها.

الأجهزة

يمكنك إرفاق الكائنات الثنائية كبيرة الحجم بالأجهزة. تظهر الصورة التالية الوثائق المرجعية Swagger لواجهات برمجة تطبيقات الإدارة. يحدد نقاط نهاية واجهة برمجة التطبيقات المتعلقة بالجهاز لاستهلاك الكائن الثنائي كبير الحجم وأي معلمات مسار مطلوبة لتمريرها إليها.

على سبيل المثال، لتحديث أو إنشاء كائن ثنائي كبير الحجم وإرفاق الكائن الثنائي كبير الحجم بجهاز، قم بإجراء طلب HTTP PATCH مصادق عليه إلى:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

المعلمة‬	استبدال بـ
YOUR_BLOB_ID	معرف الكائن الثنائي كبير الحجم المطلوب

ترجع الطلبات الناجحة كائن JSON كما هو موضح سابقا.

المسافات

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

على سبيل المثال، لإرجاع كائن ثنائي كبير الحجم مرفق بمسافة، قم بإجراء طلب HTTP GET مصادق عليه إلى:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

المعلمة‬	استبدال بـ
YOUR_BLOB_ID	معرف الكائن الثنائي كبير الحجم المطلوب

ترجع الطلبات الناجحة كائن JSON كما هو موضح سابقا.

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

المستخدمون

يمكنك إرفاق الكائنات الثنائية كبيرة الحجم بنماذج المستخدم (على سبيل المثال، لإقران صورة ملف تعريف). تعرض الصورة التالية نقاط نهاية واجهة برمجة تطبيقات المستخدم ذات الصلة وأي معلمات مسار مطلوبة، مثل id:

على سبيل المثال، لإحضار كائن ثنائي كبير الحجم مرفق بمستخدم، قم بإجراء طلب HTTP GET مصادق عليه مع أي بيانات نموذج مطلوبة إلى:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

المعلمة‬	استبدال بـ
YOUR_BLOB_ID	معرف الكائن الثنائي كبير الحجم المطلوب

ترجع الطلبات الناجحة كائن JSON كما هو موضح سابقا.

الأخطاء الشائعة

يتضمن الخطأ الشائع عدم توفير معلومات العنوان الصحيحة:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
لحل هذا الخطأ، تحقق من أن الطلب الكلي يحتوي على عنوان نوع المحتوى المناسب:
- multipart/mixed
- multipart/form-data
تحقق أيضا من أن كل مجموعة متعددة الأحزاب تحتوي على نوع محتوى مطابق مناسب.
ينشأ خطأ شائع ثان عند تعيين كائنات ثنائية كبيرة الحجم متعددة إلى نفس المورد في الرسم البياني للذكاء المكاني:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
إشعار

ستختلف سمة الرسالة استنادا إلى المورد.

يمكن إرفاق كائن ثنائي كبير الحجم واحد فقط (من كل نوع) بكل مورد داخل الرسم البياني المكاني.

لحل هذا الخطأ، قم بتحديث الكائن الثنائي كبير الحجم الموجود باستخدام عملية API HTTP PATCH المناسبة. سيؤدي القيام بذلك إلى استبدال بيانات الكائن الثنائي كبير الحجم الموجودة بالبيانات المطلوبة.

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

لمعرفة المزيد حول وثائق Swagger المرجعية ل Azure Digital Twins، اقرأ استخدام Azure Digital Twins Swagger.
لتحميل الكائنات الثنائية كبيرة الحجم من خلال Postman، اقرأ كيفية تكوين Postman.

مشاركة عبر

إضافة الكائنات الثنائية كبيرة الحجم إلى الكائنات في Azure Digital Twins

نظرة عامة على تحميل الكائنات الثنائية كبيرة الحجم

بيانات تعريف Blob

بيانات استجابة الكائنات الثنائية كبيرة الحجم

أمثلة على طلب كائن ثنائي كبير الحجم متعدد الأقسام

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

الأجهزة

المسافات

المستخدمون

الأخطاء الشائعة

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

الموارد الإضافية