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

مقالة
06/14/2023

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

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

هام

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

هام

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

ملاحظة

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

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

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

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

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

ملاحظة

ستحتاج كل هوية مدارة مرتبطة بمخزن البيانات إلى أدوار المساهمو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، الملف المستورد إلى الحاوية الخاصة بك.

يوفر لك القسمان التاليان تفاصيل حول كيفية الحصول على القيم لاستخدامها لخصائص 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

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

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

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

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

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

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

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