نسخ البيانات من Xero باستخدام Azure Data Factory أو تحليلات Synapse

مقالة
11/05/2024

ينطبق على: Azure Data Factory Azure Synapse Analytics

تلميح

جرب Data Factory في Microsoft Fabric، وهو حل تحليلي متكامل للمؤسسات. يغطي Microsoft Fabric كل شيء بدءا من حركة البيانات إلى علم البيانات والتحليلات في الوقت الحقيقي والمعلومات المهنية وإعداد التقارير. تعرف على كيفية بدء إصدار تجريبي جديد مجانا!

توضح هذه المقالة كيفية استخدام نشاط النسخ في مصنع بيانات Azure أو مسار تحليلات Synapse لنسخ البيانات من Xero. تعتمد هذه المقالة على مقالة نظرة عامة على نشاط النسخ التي تقدم نظرة عامة على نشاط النسخ.

إشعار

يتطلب موصل Xero مصادقة OAuth وليس مخصصا لاستخدام الخادم إلى الخادم.

القدرات المدعومة

موصل Xero هذا مدعوم للإمكانيات التالية:

القدرات المدعومة	IR
نشاط النسخ (مصدر/-)	(1) (2)
نشاط البحث	(1) (2)

① وقت تشغيل تكامل Azure ② وقت تشغيل التكامل المستضاف ذاتيًا

للحصول على قائمة مخازن البيانات المعتمدة كمصادر ومواضع تلقي، راجع جدول مخازن البيانات المعتمدة.

وعلى وجه التحديد، يدعم موصل Xero هذا:

مصادقة OAuth 2.0.
كافة جداول Xero (نقاط نهاية API) باستثناء "التقارير".
إصدارات Windows في هذه المقالة.

إشعار

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

الشروع في العمل

لتنفيذ نشاط النسخ باستخدام أحد المسارات، يمكنك استخدام إحدى الأدوات أو عدد تطوير البرامج التالية:

إنشاء خدمة مرتبطة ب Xero باستخدام واجهة المستخدم

استخدم الخطوات التالية لإنشاء خدمة مرتبطة ب Xero في واجهة مستخدم المدخل Azure.

استعرض للوصول إلى علامة التبويب "Manage" في مصنع بيانات Azure أو مساحة عمل Synapse، وحدد "Linked Services"، ثم انقر فوق "New":
- Azure Data Factory
- Azure Synapse
ابحث عن Xero وحدد موصل Xero.
قم بتكوين تفاصيل الخدمة، واختبر الاتصال، وأنشئ الخدمة المرتبطة الجديدة.

تفاصيل تكوين الموصل

توفر الأقسام التالية تفاصيل حول الخصائص المستخدمة لتعريف كيانات Data Factory الخاصة بموصل Xero.

خصائص الخدمة المرتبطة

يتم اعتماد الخصائص التالية لخدمة Xero المرتبطة:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية النوع إلى: Xero	‏‏نعم‬
connectionProperties	مجموعة من الخصائص التي تعرف كيفية الاتصال ب Xero.	‏‏نعم‬
تحت `connectionProperties`:
مضيف	نقطة النهاية لخادم Xero (`api.xero.com`).	‏‏نعم‬
نوع المصادقة	القيم المسموح بها هي `OAuth_2.0` و`OAuth_1.0`.	‏‏نعم‬
consumerKey	بالنسبة إلى OAuth 2.0، حدد معرف العميل لتطبيق Xero الخاص بك. بالنسبة إلى OAuth 1.0، حدد مفتاح المستهلك المقترن بتطبيق Xero. ضع علامة على هذا الحقل باعتباره SecureString لتخزينه بشكل آمن، أو قم بالإشارة إلى بيانات سرية مخزنة في Azure Key Vault.	‏‏نعم‬
privateKey	بالنسبة إلى OAuth 2.0، حدد سر العميل لتطبيق Xero الخاص بك. بالنسبة إلى OAuth 1.0، حدد المفتاح الخاص من ملف pem. الذي تم إنشاؤه لتطبيق Xero الخاص. ملاحظة لإنشاء ملف privatekey.pem بعدد 512 باستخدام `openssl genrsa -out privatekey.pem 512`، 1024 غير مدعوم. تضمين كافة النص من ملف .pem بما في ذلك نهايات سطر Unix(\n)، راجع العينة أدناه. ضع علامة على هذا الحقل باعتباره SecureString لتخزينه بشكل آمن، أو قم بالإشارة إلى بيانات سرية مخزنة في Azure Key Vault.	‏‏نعم‬
tenantId	هوية المستأجر المرتبطة بتطبيق Xero الخاص بك. ينطبق على مصادقة OAuth 2.0. تعرف على كيفية الحصول على هوية المستأجر من التحقق من المستأجرين المخولين لك بالوصول إلى القسم.	نعم للمصادقة OAuth 2.0
refreshToken	ينطبق على مصادقة OAuth 2.0. يرتبط رمز التحديث OAuth 2.0 بتطبيق Xero ويُستخدَم لتحديث الرمز المميز للوصول؛ تنتهي صلاحية الرمز المميز للوصول بعد 30 دقيقة. تعرف على كيفية عمل تدفق التخويل Xero وكيفية الحصول على رمز التحديث المميز من هذه المقالة. للحصول على رمز مميز للتحديث، يجب طلب نطاق offline_access. معرفة القيد: ملاحظة تعيد Xero تعيين رمز التحديث المميز بعد استخدامه لتحديث الرمز المميز للوصول. بالنسبة لحمل العمل التشغيلي، قبل تشغيل كل نشاط نسخ، تحتاج إلى تعيين رمز تحديث مميز صالح للخدمة لاستخدامها. ضع علامة على هذا الحقل باعتباره SecureString لتخزينه بشكل آمن، أو قم بالإشارة إلى بيانات سرية مخزنة في Azure Key Vault.	نعم للمصادقة OAuth 2.0
useEncryptedEndpoints	يحدد ما إذا كانت نقاط نهاية مصدر البيانات مشفرة باستخدام HTTPS. القيمة الافتراضية هي صواب.	لا
useHostVerification	تحديد ما إذا كان يجب طلب اسم المضيف في شهادة الخادم لمطابقة اسم مضيف الخادم عند الاتصال عبر بروتوكول أمان طبقة النقل. القيمة الافتراضية هي صواب.	لا
usePeerVerification	يُحدد ما إذا كان سيتم التحقق من هوية الخادم عند الاتصال عبر TLS. القيمة الافتراضية هي صواب.	لا

مثال: مصادقة OAuth 2.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": { 
                "host": "api.xero.com",
                "authenticationType":"OAuth_2.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<client ID>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<client secret>"
                },
                "tenantId": "<tenant ID>", 
                "refreshToken": {
                    "type": "SecureString",
                    "value": "<refresh token>"
                }, 
                "useEncryptedEndpoints": true, 
                "useHostVerification": true, 
                "usePeerVerification": true
            }            
        }
    }
}

مثال: مصادقة OAuth 1.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": {
                "host": "api.xero.com", 
                "authenticationType":"OAuth_1.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<consumer key>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<private key>"
                }, 
                "useEncryptedEndpoints": true,
                "useHostVerification": true,
                "usePeerVerification": true
            }
        }
    }
}

نموذج قيمة المفتاح الخاص:

تضمين كافة النص من ملف .pem بما في ذلك نهايات سطر Unix(\n).

"-----BEGIN RSA PRIVATE KEY-----\nMII***************************************************P\nbu****************************************************s\nU/****************************************************B\nA*****************************************************W\njH****************************************************e\nsx*****************************************************l\nq******************************************************X\nh*****************************************************i\nd*****************************************************s\nA*****************************************************dsfb\nN*****************************************************M\np*****************************************************Ly\nK*****************************************************Y=\n-----END RSA PRIVATE KEY-----"

خصائص مجموعة البيانات

للحصول على قائمة كاملة بالأقسام والخصائص المتوفرة لتعريف مجموعات البيانات، راجع مقالة مجموعات البيانات. يوفر هذا القسم قائمة بالخصائص التي تدعمها مجموعة بيانات Xero.

لنسخ البيانات من Xero، قم بتعيين خاصية نوع مجموعة البيانات إلى XeroObject. تدعم الخصائص التالية:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية نوع مجموعة البيانات إلى: XeroObject	‏‏نعم‬
اسم الجدول	ضع اسمًا للجدول.	لا (إذا تم تحديد "الاستعلام" في مصدر النشاط)

مثال

{
    "name": "XeroDataset",
    "properties": {
        "type": "XeroObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Xero linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

انسخ خصائص النشاط

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

Xero كمصدر

لنسخ البيانات من Xero، قم بتعيين نوع المصدر في نشاط النسخ إلى XeroSource. تُدعم الخصائص التالية في قسم مصدر نشاط النسخ:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية نوع مصدر نشاط النسخ إلى: XeroSource	‏‏نعم‬
استعلام	استخدم استعلام SQL المخصص لقراءة البيانات. على سبيل المثال: `"SELECT * FROM Contacts"`.	لا (إذا تم تحديد "tableName" في مجموعة البيانات)

مثال:

"activities":[
    {
        "name": "CopyFromXero",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Xero input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "XeroSource",
                "query": "SELECT * FROM Contacts"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

لاحظ ما يلي عند تحديد استعلام Xero:

سيتم تقسيم الجداول ذات العناصر المعقدة إلى جداول متعددة. على سبيل المثال، تحتوي العمليات البنكية على بنية بيانات معقدة "LineItems"، لذلك يتم تعيين العمليات المصرفية إلى جدول Bank_Transaction وBank_Transaction_Line_Items، مع Bank_Transaction_ID كمفتاح خارجي لربطها ببعضها البعض.
تتوفر بيانات Xero من خلال مخططين: Minimal (افتراضي) وComplete. يحتوي المخطط "إكمال" على جداول استدعاء متطلبة مسبقاً تتطلب بيانات إضافية (مثل عمود المعرف) قبل إجراء الاستعلام المطلوب.

تحتوي الجداول التالية على نفس المعلومات في مخطط "Minimal" و"Complete". لتقليل عدد استدعاءات API، استخدم مخطط "Minimal" (افتراضي).

Bank_Transactions
Contact_Groups
جهات الاتصال
Contacts_Sales_Tracking_Categories
Contacts_Phones
Contacts_Addresses
Contacts_Purchases_Tracking_Categories
Credit_Notes
Credit_Notes_Allocations
Expense_Claims
Expense_Claim_Validation_Errors
الفواتير
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
المبالغ الزائده
Overpayments_Allocations
المدفوعات المسبقة
Prepayments_Allocations
إيصالات
Receipt_Validation_Errors
Tracking_Categories

يمكن الاستعلام عن الجداول التالية فقط مع المخطط الكامل:

Complete.Bank_Transaction_Line_Items
Complete.Bank_Transaction_Line_Item_Tracking
Complete.Contact_Group_Contacts
Complete.Contacts_Contact_ Persons
Complete.Credit_Note_Line_Items
Complete.Credit_Notes_Line_Items_Tracking
Complete.Expense_Claim_ Payments
Complete.Expense_Claim_Receipts
Complete.Invoice_Line_Items
Complete.Invoices_Line_Items_Tracking
Complete.Manual_Journal_Lines
Complete.Manual_Journal_Line_Tracking
Complete.Overpayment_Line_Items
Complete.Overpayment_Line_Items_Tracking
Complete.Prepayment_Line_Items
Complete.Prepayment_Line_Item_Tracking
Complete.Receipt_Line_Items
Complete.Receipt_Line_Item_Tracking
Complete.Tracking_Category_Options

بحث عن خصائص النشاط

لمعرفة تفاصيل حول الخصائص، تحقق من نشاط البحث.

للاطلاع على قائمة متاجر البيانات المدعومة، راجع مخازن البيانات المدعمة.

مشاركة عبر

نسخ البيانات من Xero باستخدام Azure Data Factory أو تحليلات Synapse

القدرات المدعومة

الشروع في العمل

إنشاء خدمة مرتبطة ب Xero باستخدام واجهة المستخدم

تفاصيل تكوين الموصل

خصائص الخدمة المرتبطة

خصائص مجموعة البيانات

انسخ خصائص النشاط

Xero كمصدر

بحث عن خصائص النشاط

الملاحظات

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

مشاركة عبر

نسخ البيانات من Xero باستخدام Azure Data Factory أو تحليلات Synapse

القدرات المدعومة

الشروع في العمل

إنشاء خدمة مرتبطة ب Xero باستخدام واجهة المستخدم

تفاصيل تكوين الموصل

خصائص الخدمة المرتبطة

خصائص مجموعة البيانات

انسخ خصائص النشاط

Xero كمصدر

بحث عن خصائص النشاط

المحتوى ذو الصلة

الملاحظات

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