كيفية إنشاء سجل البيانات

مقالة
09/16/2024

إشعار

إيقاف خدمة سجل البيانات خرائط Azure

تم الآن إهمال خدمة سجل البيانات خرائط Azure وسيتم إيقافها في 9/30/25. لمزيد من المعلومات، راجع إعلان انتهاء العمر الافتراضي لسجل بيانات خرائط Azure.

تمكنك خدمة تسجيل البيانات من تسجيل محتوى البيانات في حساب تخزين Azure باستخدام حساب خرائط Azure الخاص بك. قد يتضمن مثال على البيانات مجموعة من Geofences المستخدمة في خدمة خرائط Azure Geofencing. مثال آخر هو ملفات ZIP التي تحتوي على حزم رسومية (DWG) أو ملفات GeoJSON التي خرائط Azure يستخدمها المنشئ لإنشاء الخرائط الداخلية أو تحديثها.

المتطلبات الأساسية

هام

تستخدم هذه المقالة عنوان URL الجغرافي us.atlas.microsoft.com. إذا لم يتم إنشاء حسابك في الولايات المتحدة، فيجب عليك استخدام عنوان URL جغرافي مختلف. لمزيد من المعلومات، راجع الوصول إلى خدمات المنشئ.
في أمثلة URL في هذه المقالة، ستحتاج إلى استبدال:
- {Azure-Maps-Subscription-key}باستخدام مفتاح اشتراك خرائط Azure.
- {udid} مع معرف بيانات المستخدم الخاص بسجل البيانات الخاص بك. لمزيد من المعلومات، راجع معرف بيانات المستخدم.

الاستعداد لتسجيل البيانات في خرائط Azure

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

إنشاء هويات مدارة

هناك نوعان من الهويات المدارة: مخصص من قِبَل النظام ومخصص من قِبَل المستخدم. الهويات المدارة المعينة من قبل النظام لها دورة حياتها المرتبطة بالموارد التي أنشأتها. يمكن استخدام الهويات المدارة المعينة من قبل المستخدم على موارد متعددة. لمزيد من المعلومات، راجع الهويات المدارة لموارد Azure.

استخدم الخطوات التالية لإنشاء هوية مدارة، وإضافتها إلى حساب خرائط Azure الخاص بك.

المعين من قبل النظام
تم تعيينه من قبل المستخدم

إنشاء هوية مدارة معينة من قبل النظام:

انتقل إلى حساب خرائط Azure في مدخل Microsoft Azure.
حدد Identity من قسم Settings في القائمة اليسرى.
قم بتبديل الحالة إلى تشغيل.

لمزيد من المعلومات، راجع الهويات المدارة لموارد Azure.

إنشاء حاوية وتحميل ملفات البيانات

قبل إضافة ملفات إلى سجل بيانات، يجب تحميلها في حاوية في حساب تخزين Azure الخاص بك. تشبه الحاويات الدليل في نظام الملفات، وهي كيفية تنظيم ملفاتك في حساب تخزين Azure الخاص بك.

لإنشاء حاوية في مدخل Microsoft Azure، اتبع هذه الخطوات:

من داخل حساب تخزين Azure، حدد Containers من قسم Data storage في جزء التنقل.
حدد + Container في جزء Containers لإظهار جزء New container .
حدد Create لإنشاء الحاوية.

بمجرد إنشاء الحاوية الخاصة بك، يمكنك تحميل الملفات إليها.
بمجرد إنشاء الحاوية، حددها.
حدد تحميل من شريط الأدوات، وحدد ملفا واحدا أو أكثر
حدد الزر تحميل.

إضافة مخزن بيانات

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

هام

يجب أن تكون جميع حسابات التخزين المرتبطة بحساب خرائط Azure في نفس الموقع الجغرافي. لمزيد من المعلومات، راجع النطاق الجغرافي للخدمة خرائط Azure.

إشعار

إذا لم يكن لديك حساب تخزين، فشاهد إنشاء حساب تخزين.

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

يظهر مخزن البيانات الجديد الآن في قائمة مخازن البيانات.

تعيين أدوار للهويات المدارة وإضافتها إلى مخزن البيانات

بمجرد إنشاء الهويات المدارة ومخزن البيانات، يمكنك إضافة الهويات المدارة إلى مخزن البيانات، وتعيين أدوار Contributor وStorage Blob Data Reader في نفس الوقت. في حين أنه من الممكن إضافة أدوار إلى الهويات المدارة مباشرة في الهويات المدارة أو حساب التخزين، وهو ما يمكنك القيام به بسهولة أثناء ربطها في نفس الوقت بمخزن البيانات خرائط Azure مباشرة في جزء مخزن البيانات.

إشعار

ستحتاج كل هوية مدارة مرتبطة بمخزن البيانات إلى أدوار Contributor وStorage Blob Data Reader الممنوحة لهم. إذا لم يكن لديك الأذونات المطلوبة لمنح أدوار للهويات المدارة، فراجع مسؤول Azure. لتعيين أدوار للهويات المدارة وربطها بمتجير بيانات:

حدد Datastore من القائمة اليسرى في حساب خرائط Azure الخاص بك.
حدد مخزن بيانات واحدا أو أكثر من القائمة، ثم تعيين أدوار.
حدد الهوية المدارة لإقرانها بمتوابع البيانات المحددة من القائمة المنسدلة.
حدد كل من Contributor وStorage Blob Data Reader في القائمة المنسدلة Roles لتعيينها .
حدد الزر تعيين‬.

خصائص سجل البيانات

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

هناك خصائص AzureBlob التي تمررها في نص طلب HTTP، ومعرف بيانات المستخدم الذي تم تمريره في عنوان URL.

The AzureBlob

AzureBlob هو كائن JSON الذي يحدد الخصائص المطلوبة لإنشاء سجل البيانات.

الخاصية	‏‏الوصف
`kind`	يحدد نوع الكائن الذي يتم تسجيله. حاليا AzureBlob هو النوع الوحيد المدعوم.
`dataFormat`	تنسيق البيانات للملف الموجود في blobUrl. يمكن أن يكون تنسيقه إما GeoJSON للخدمة المكانية (مهملة¹) أو ZIP لخدمة التحويل (مهمل¹).
`msiClientId`	معرف الهوية المدارة المستخدمة لإنشاء سجل البيانات.
`linkedResource`	معرف مخزن البيانات المسجل في حساب خرائط Azure. يحتوي مخزن البيانات على ارتباط إلى الملف الذي يتم تسجيله.
`blobUrl`	عنوان URL يشير إلى موقع AzurebBlob، الملف المستورد إلى الحاوية الخاصة بك.

¹ خرائط Azure Creator، ويتم الآن إهمال سجل البيانات والخدمات المكانية وسيتم إيقافها في 9/30/25.

يوفر لك القسمان التاليان تفاصيل حول كيفية الحصول على القيم لاستخدامها لخصائص msiClientId، blobUrl .

الخاصية msiClientId

msiClientId الخاصية هي معرف الهوية المدارة المستخدمة لإنشاء سجل البيانات. هناك نوعان من الهويات المدارة: مخصص من قِبَل النظام ومخصص من قِبَل المستخدم. الهويات المدارة المعينة من قبل النظام لها دورة حياتها المرتبطة بالموارد التي أنشأتها. يمكن استخدام الهويات المدارة المعينة من قبل المستخدم على موارد متعددة. لمزيد من المعلومات، راجع الهويات المدارة لموارد Azure.

المعين من قبل النظام
تم تعيينه من قبل المستخدم

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

القيمة المستخدمة للخاصية msiClientId هي معرف العميل للهوية المدارة المعينة من قبل المستخدم.

في حساب خرائط Azure، حدد Identity من القائمة اليسرى.
مرر مؤشر الماوس فوق اسم التعريف المدار حتى يظهر كارتباط، ثم حدده.
انسخ معرف العميل.

الخاصية blobUrl

blobUrl الخاصية هي المسار إلى الملف الذي يتم تسجيله. يمكنك الحصول على هذه القيمة من الحاوية التي تمت إضافتها إليها. سجل البيانات

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

معرف بيانات المستخدم

معرف بيانات المستخدم (udid) لسجل البيانات هو GUID معرف من قبل المستخدم يجب أن يتوافق مع نمط Regex التالي:

^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$

تلميح

udid هو GUID معرف من قبل المستخدم يجب توفيره عند إنشاء سجل بيانات. إذا كنت تريد التأكد من أن لديك معرف فريد عمومي (GUID)، ففكر في إنشائه عن طريق تشغيل أداة إنشاء GUID مثل برنامج سطر الأوامر Guidgen.exe (متوفر مع Visual Studio).

إنشاء سجل بيانات

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

إشعار

الحد الأقصى لحجم الملف الذي يمكن تسجيله باستخدام مخزن بيانات خرائط Azure هو غيغابايت واحد.

لإنشاء سجل بيانات:

المعين من قبل النظام
تم تعيينه من قبل المستخدم

قم بتوفير المعلومات اللازمة للإشارة إلى حساب التخزين الذي تتم إضافته إلى سجل البيانات في نص طلب HTTP الخاص بك. يجب أن تكون المعلومات بتنسيق JSON وأن تحتوي على الحقول التالية:
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
إشعار

عند استخدام الهويات المدارة المعينة من قبل النظام، ستحصل على خطأ إذا قمت بتوفير قيمة للخاصية msiClientId في طلب HTTP الخاص بك.

لمزيد من المعلومات حول الخصائص المطلوبة في نص طلب HTTP، راجع خصائص سجل البيانات.
بمجرد أن يكون نص طلب HTTP جاهزا، قم بتنفيذ طلب HTTP PUT التالي:
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
لمزيد من المعلومات حول الخاصية udid ، راجع معرف بيانات المستخدم.
انسخ قيمة مفتاح Operation-Location من عنوان الاستجابة.

قم بتوفير المعلومات اللازمة للإشارة إلى حساب التخزين الذي تتم إضافته إلى سجل البيانات في نص طلب HTTP الخاص بك. يجب أن تكون المعلومات بتنسيق JSON وأن تحتوي على الحقول التالية:
```
{
"kind": "AzureBlob",
    "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "{The client ID of the managed identity}",
        "linkedResource": "{datastore ID}",
        "blobUrl": "https://teststorageaccount.blob.core.windows.net/testcontainer/test.geojson"
    }
}
```
إشعار

عند استخدام الهويات المدارة المعينة من قبل المستخدم، ستحصل على خطأ إذا لم تقدم قيمة للخاصية msiClientId في طلب HTTP الخاص بك.

لمزيد من المعلومات حول الخصائص المطلوبة في نص طلب HTTP، راجع خصائص سجل البيانات.
بمجرد أن يكون نص طلب HTTP جاهزا، قم بتنفيذ طلب HTTP PUT التالي:
```
https://us.atlas.microsoft.com/dataRegistries/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key} 
```
لمزيد من المعلومات حول الخاصية udid ، راجع معرف بيانات المستخدم.
انسخ قيمة مفتاح Operation-Location من عنوان الاستجابة.

تلميح

إذا تم تعديل محتويات ملف مسجل مسبقا، فسيفشل في التحقق من صحة البيانات ولن يكون قابلا للاستخدام في خرائط Azure حتى يتم إعادة تسجيله. لإعادة تسجيل ملف، أعد تشغيل طلب التسجيل، ومرر نفس AzureBlob المستخدم لإنشاء التسجيل الأصلي. قيمة مفتاح Operation-Location هي عنوان URL للحالة الذي ستستخدمه للتحقق من حالة إنشاء سجل البيانات في القسم التالي، ويحتوي على معرف العملية المستخدم بواسطة واجهة برمجة تطبيقات عملية Get.

إشعار

لن تحتوي قيمة مفتاح Operation-Location على subscription-key، ستحتاج إلى إضافة ذلك إلى عنوان URL للطلب عند استخدامه للتحقق من حالة إنشاء سجل البيانات.

التحقق من حالة إنشاء سجل البيانات

للتحقق (اختياريا) من حالة عملية إنشاء سجل البيانات، أدخل عنوان URL للحالة الذي نسخته في قسم إنشاء سجل بيانات، وأضف مفتاح الاشتراك كمعلمة سلسلة استعلام. يجب أن يبدو الطلب مشابها ل URL التالي:

https://us.atlas.microsoft.com/dataRegistries/operations/{udid}?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Primary-Subscription-key}

الحصول على قائمة بجميع الملفات في سجل البيانات

استخدم طلب القائمة للحصول على قائمة بجميع الملفات المسجلة في حساب خرائط Azure:

https://us.atlas.microsoft.com/dataRegistries?api-version=2023-06-01&subscription-key={Azure-Maps-Subscription-key}

يوضح النموذج التالي ثلاث حالات محتملة، مكتملة، قيد التشغيل وفشلت:

{
  "value": [
    {
      "udid": "f6495f62-94f8-0ec2-c252-45626f82fcb2",
      "description": "Contoso Indoor Design",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "zip",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path1.zip",
        "sizeInBytes": 29920,
        "contentMD5": "CsFxZ2YSfxw3cRPlqokV0w=="
      },
      "status": "Completed"
    },
    {
      "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "msiClientId": "3263cad5-ed8b-4829-b72b-3d1ba556e373",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path2.geojson",
        "sizeInBytes": 1339
      },
      "status": "Running"
    },
    {
      "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
      "description": "Contoso Geofence GeoJSON",
      "kind": "AzureBlob",
      "azureBlob": {
        "dataFormat": "geojson",
        "linkedResource": "my-storage-account",
        "blobUrl": "https://mystorageaccount.blob.core.windows.net/my-container/my/blob/path3.geojson",
        "sizeInBytes": 1650,
        "contentMD5": "rYpEfIeLbWZPyaICGEGy3A=="
      },
      "status": "Failed",
      "error": {
        "code": "ContentMD5Mismatch",
        "message": "Actual content MD5: sOJMJvFParkSxBsvvrPOMQ== doesn't match expected content MD5: CsFxZ2YSfxw3cRPlqokV0w==."
      }
    }
  ]
}

البيانات التي يتم إرجاعها عند تشغيل طلب القائمة مشابهة للبيانات المقدمة عند إنشاء سجل مع بعض الإضافات:

خاصية	الوصف
contentMD5	تم إنشاء تجزئة MD5 من محتويات الملف الذي يتم تسجيله. لمزيد من المعلومات، راجع التحقق من صحة البيانات
sizeInBytes	حجم المحتوى بالبايت.

استبدال سجل بيانات

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

التحقق من صحة البيانات

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

مشاركة عبر

كيفية إنشاء سجل البيانات

المتطلبات الأساسية

الاستعداد لتسجيل البيانات في خرائط Azure

إنشاء هويات مدارة

إنشاء حاوية وتحميل ملفات البيانات

إضافة مخزن بيانات

تعيين أدوار للهويات المدارة وإضافتها إلى مخزن البيانات

خصائص سجل البيانات

The AzureBlob

الخاصية msiClientId

الخاصية blobUrl

معرف بيانات المستخدم

إنشاء سجل بيانات

التحقق من حالة إنشاء سجل البيانات

الحصول على قائمة بجميع الملفات في سجل البيانات

استبدال سجل بيانات

التحقق من صحة البيانات

الملاحظات

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