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

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

تلميح

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

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

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

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

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

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

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

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

• مصادقة OAuth 2.0 وOAuth 1.0. بالنسبة إلى OAuth 1.0، يدعم الموصل تطبيق Xero الخاص ولكن ليس التطبيق العام.
• كافة جداول Xero (نقاط نهاية API) باستثناء "التقارير".

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

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

• أداة نسخ البيانات
• مدخل Azure
• The .NET SDK
• عدة تطوير برامج Python
• Azure PowerShell
• واجهة برمجة تطبيقات REST
• قالب Azure Resource Manager

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

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

1. استعرض للوصول إلى علامة التبويب "Manage" في مصنع بيانات Azure أو مساحة عمل Synapse، وحدد "Linked Services"، ثم انقر فوق "New":

   Azure Data Factory

   

   Azure Synapse

   

2. ابحث عن Xero وحدد موصل Xero.

   

3. قم بتكوين تفاصيل الخدمة، واختبر الاتصال، وأنشئ الخدمة المرتبطة الجديدة.

   

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

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

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

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

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

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