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

مقدمة

توفّر Linking API واجهة موثوقة لإعداد المستخدمين وإعادة توجيههم مباشرةً إلى تقرير في مركز البيانات من خلال عنوان URL. عندما يتّبع المستخدمون عنوان URL خاصًا بواجهة Linking API، سيحصلون على تجربة مبسطة تتيح لهم الاطّلاع على بياناتهم والتفاعل معها بسرعة.

يوضّح هذا المستند التنسيق المطلوب لعناوين URL الخاصة بواجهة Linking API والمعلَمات المتاحة.

حالة الاستخدام والمزايا

يمكن استخدام Linking API لتوفير تقارير معدّة مسبقًا لعملائك ليتمكّنوا من الاطّلاع على بياناتهم والتفاعل معها. في ما يلي المزايا الرئيسية لواجهة Linking API:

تجربة إنشاء تقارير بنقرة واحدة لعملائك:
- يتم توفير إعدادات البيانات في عنوان URL، لذا لا يحتاج المستخدمون إلى ضبط التقرير لبياناتهم.
- يمكن للمستخدمين حفظ التقرير بنقرة واحدة وإعادة زيارته في أي وقت.
إنشاء التقارير على نطاق واسع تساهم Linking API في تقليل الوقت اللازم لتكرار التقارير أو إنشاء تقارير جديدة.
تفعيل عمليات دمج المنتجات تتيح لك الواجهة الثابتة دمج "مركز البيانات" في سير عمل أحد المنتجات.

آلية العمل

يوضّح ما يلي كيفية تفاعل المطوّرين والمستخدمين مع Linking API.

سير عمل المطوّر لواجهة Linking API

يُعدّ المطوّر تقارير النماذج ومصادر البيانات وينسّق عنوان URL لواجهة Linking API. في ما يلي سير العمل المعتاد للمطوّرين:

حدِّد ما إذا كنت تريد استخدام تقرير فارغ أو نموذج التقرير التلقائي الذي يوفّره "مركز البيانات" أو إنشاء تقرير في "مركز البيانات" سيتم استخدامه كنموذج. ويشمل ذلك ضبط إعدادات مصادر بيانات النموذج.
تنسيق عنوان URL لواجهة Linking API بما يتناسب مع حالة الاستخدام المحدّدة حدِّد نموذج التقرير والمعلَمات الأخرى، بما في ذلك اسم التقرير واسم مصدر البيانات وإعدادات مصدر البيانات، إذا كان ذلك منطبقًا.
استخدِم عنوان URL الخاص بواجهة Linking API لتوجيه المستخدمين إلى التقرير.

تجربة المستخدم في ربط حسابات واجهة برمجة التطبيقات

يتبع المستخدم عنوان URL لواجهة Linking API، والذي سيوجّه المستخدم إلى تقرير في مركز البيانات يتيح له عرض البيانات التي يمكنه الوصول إليها والتفاعل معها، وذلك إذا كان المطوّر قد ضبط عنوان URL بشكل صحيح. قد تكون تجربة المستخدم النموذجية على النحو التالي:

في المتصفّح، ينتقل المستخدم إلى خدمة تم دمجها مع Linking API.
يدعو الحث على اتّخاذ إجراء المستخدم إلى النقر على رابط لعرض بياناته في "مركز البيانات".
ينقر المستخدم على الرابط ويتم توجيهه إلى تقرير في "مركز البيانات". يتم تحميل التقرير ويصبح بإمكان المستخدم الاطّلاع على بياناته والتفاعل معها.
ينقر المستخدم على "تعديل ومشاركة". يتم حفظ التقرير في حساب المستخدم على "مركز البيانات".
يمكن للمستخدم الآن الوصول إلى نسخته من التقرير والتحكّم فيها بشكل كامل. ويمكنهم الاطّلاع على الملفات وتعديلها ومشاركتها في أي وقت.

المتطلبات

لضمان عمل عنوان URL الخاص بواجهة Linking API على النحو المتوقّع، يجب استيفاء الشروط التالية:

تقرير يُستخدَم كنموذج في حال عدم توفيرها، يمكن استخدام تقرير فارغ أو تقرير تلقائي يوفّره "مركز البيانات".
يجب أن يكون لدى مستخدمي عنوان URL الخاص بـ Linking API إذن بالاطّلاع على تقرير النموذج على الأقل. استنادًا إلى نوع مصادر البيانات المستخدَمة في التقرير والإعدادات المقدَّمة من خلال Linking API، قد يحتاج المستخدمون أيضًا إلى إذن بالاطّلاع على مصادر البيانات. راجِع مقالة أذونات النماذج للحصول على التفاصيل.
يجب أن يتيح نوع أداة الربط لكل مصدر بيانات إمكانية الإعداد من خلال Linking API. يُرجى الرجوع إلى مرجع الموصل للاطّلاع على قائمة بالموصلات المتوافقة.
يجب أن يكون لدى مستخدمي عنوان URL الخاص بواجهة Linking API إذن الوصول إلى البيانات التي تم ضبطها في عنوان URL الخاص بواجهة Linking API. إذا لم يكن لدى المستخدم إذن بالوصول إلى البيانات الأساسية، ستعرض أي مكوّنات تقرير تابعة خطأً.

معلمات عنوان URL

يجب أن يكون عنوان URL لواجهة Linking API بالشكل التالي:

https://lookerstudio.google.com/reporting/create?parameters

من المتوقّع أن يتم استخدام عنوان URL في سياق متصفّح ويب، وعادةً ما يتم ذلك من خلال نقر المستخدم على رابط أو إعادة توجيهه إلى عنوان URL. يمكن أيضًا استخدامها من أجل تضمين تقرير.

مثال على عنوان URL

في ما يلي مثال على عنوان URL لواجهة Linking API. تم ضبط اسم التقرير وإعداد مصدر بيانات واحد في BigQuery:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.connector=bigQuery
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

بعض مَعلمات عناوين URL مطلوبة، والبعض الآخر اختياري. في ما يلي قائمة بالمعلَمات المستخدَمة لتحديد عنوان URL لواجهة Linking API:

مَعلمات التحكّم

تحدّد مَعلمات التحكّم حالة التقرير عند عرضه من خلال عنوان URL الخاص بواجهة Linking API.

اسم المعلَمة	الوصف
`c.reportId`	اختياريّ. رقم تعريف التقرير الخاص بالنموذج سيتم فتح "مركز البيانات" وإعداد التقرير المحدّد. للحصول على تفاصيل حول كيفية العثور على المعرّف، يُرجى الاطّلاع على مقالة معرّف البلاغ. في حال عدم تحديد ذلك، يتم استخدام تقرير فارغ أو نموذج تقرير تلقائي، راجِع مقالة استخدام تقرير فارغ أو تلقائي للحصول على التفاصيل.
`c.pageId`	اختياريّ. معرّف الصفحة الأولية التي سيتم تحميلها في التقرير. يتم تلقائيًا عرض الصفحة الأولى من التقرير في حال عدم تحديد أي قيمة.
`c.mode`	اختياريّ. وضع التقرير الأوّلي أحد الخيارين `view` أو `edit`. يتم ضبط القيمة تلقائيًا على `view` في حال عدم تحديدها.
`c.explain`	اختياريّ. تحدّد هذه السمة ما إذا كان سيتم عرض مربّع حوار المعلومات/تصحيح الأخطاء. اضبط القيمة على `true` لعرض زر مربّع الحوار. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. يمكنك الاطّلاع على تحديد المشاكل وحلّها في ما يتعلّق بإعدادات العلامة لمعرفة المزيد.

مثال

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &c.pageId=g7u8s9
  &c.mode=edit
  &r.reportName=MyNewReport
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

مَعلمات التقرير

تتجاوز مَعلمات التقارير خصائص التقارير.

اسم المعلَمة الوصف

اسم المعلَمة	الوصف
`r.reportName`	اختياريّ. تُستخدَم لضبط اسم التقرير. إذا لم يتم تحديدها، سيتم تلقائيًا استخدام اسم تقرير النموذج.
`r.measurementId`	اختياريّ. يضبط هذا الحقل معرّفات القياس في "إحصاءات Google" على قياس استخدام التقارير. استخدِم الفاصلة للفصل بين أرقام التعريف المتعدّدة. إذا لم يتم تحديد `r.measurementId` و`r.keepMeasurementId`، سيتم تلقائيًا ضبط إعداد تقرير أرقام تعريف القياس في "إحصاءات Google" على "لم يتم الضبط". في حال ضبط كل من `r.measurementId` و`r.keepMeasurementId`، ستكون الأولوية لـ `r.keepMeasurementId` في ضبط المعرّف.
`r.keepMeasurementId`	اختياريّ. اضبط القيمة على `true` لاستخدام نموذج التقرير معرّفات القياس في "إحصاءات Google". يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. إذا لم يتم تحديد `r.measurementId` و`r.keepMeasurementId`، سيتم تلقائيًا ضبط إعداد تقرير أرقام تعريف القياس في "إحصاءات Google" على "لم يتم الضبط". في حال ضبط كل من `r.measurementId` و`r.keepMeasurementId`، ستكون الأولوية لـ `r.keepMeasurementId` في ضبط المعرّف.

r.reportName

اختياريّ. تُستخدَم لضبط اسم التقرير. إذا لم يتم تحديدها، سيتم تلقائيًا استخدام اسم تقرير النموذج.

r.measurementId

اختياريّ. يضبط هذا الحقل معرّفات القياس في "إحصاءات Google" على قياس استخدام التقارير. استخدِم الفاصلة للفصل بين أرقام التعريف المتعدّدة.

إذا لم يتم تحديد r.measurementId وr.keepMeasurementId، سيتم تلقائيًا ضبط إعداد تقرير أرقام تعريف القياس في "إحصاءات Google" على "لم يتم الضبط". في حال ضبط كل من r.measurementId وr.keepMeasurementId، ستكون الأولوية لـ r.keepMeasurementId في ضبط المعرّف.

r.keepMeasurementId

اختياريّ. اضبط القيمة على true لاستخدام نموذج التقرير معرّفات القياس في "إحصاءات Google". يتم ضبط القيمة تلقائيًا على false في حال عدم تحديدها.

مثال

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &r.measurementId=G-XXXXXXXXXX
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.projectId=project-1234
  &ds.ds0.type=TABLE
  &ds.ds0.datasetId=456
  &ds.ds0.tableId=789

مَعلمات مصدر البيانات

تسمح لك مَعلمات مصدر البيانات بتحديد إعدادات مصدر البيانات والبيانات التي سيتم الوصول إليها لمصادر البيانات في التقرير النموذجي.

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

للاطّلاع على تفاصيل حول كيفية العثور على مصدر بيانات alias، يُرجى الاطّلاع على الاسم المستعار لمصدر البيانات.

مَعلمات مصدر البيانات

المَعلمات التالية شائعة في جميع أنواع أدوات الربط:

الاسم	الوصف
`ds.alias.datasourceName`	اختياريّ. تضبط هذه السمة اسم مصدر البيانات. في حال عدم تحديد `ds.datasourceName` و`ds.keepDatasourceName`، سيتم تلقائيًا استخدام اصطلاح تسمية يتضمّن نوع أداة الربط ووقت الإنشاء (مثلاً samples - 12/12/21, 10:53 PM) كاسم لمصدر البيانات. في حال ضبط `ds.datasourceName` و`ds.keepDatasourceName`، تكون الأولوية لـ `ds.datasourceName` في تحديد اسم مصدر البيانات.
`ds.alias.keepDatasourceName`	اختياريّ. اضبط القيمة على `true` لاستخدام اسم مصدر بيانات النموذج. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. في حال عدم تحديد `ds.datasourceName` و`ds.keepDatasourceName`، سيتم تلقائيًا استخدام اصطلاح تسمية يتضمّن نوع أداة الربط ووقت الإنشاء (مثلاً، samples - 12/12/21, 10:53 PM) كاسم لمصدر البيانات. في حال ضبط `ds.datasourceName` و`ds.keepDatasourceName`، تكون الأولوية لـ `ds.datasourceName` في تحديد اسم مصدر البيانات.
`ds.alias.connector`	اختياريّ. نوع الموصّل لمصدر البيانات. لمزيد من المعلومات حول أنواع الموصلات المتوافقة، راجِع مرجع الموصل. في حال ضبطها، يجب تحديد جميع مَعلمات الموصّل المطلوبة لنوع الموصّل في عنوان URL الخاص بواجهة Linking API، وسيتم استبدال إعدادات مصدر بيانات النموذج بالكامل. في حال عدم تحديدها، يمكن تحديد صفر أو أكثر من مَعلمات أداة الربط لنوع أداة الربط في عنوان URL الخاص بواجهة Linking API. سيتم استخدام إعدادات مصدر بيانات النموذج لتحديد أي مَعلمات لم يتم توفيرها في عنوان URL الخاص بواجهة Linking API. للحصول على تفاصيل حول كيفية تحديد نوع الموصّل لمصدر بيانات النموذج، يُرجى الاطّلاع على نوع الموصّل. لمزيد من المعلومات حول تأثير المَعلمة `ds.connector` في تحديد ما إذا كان سيتم استبدال إعدادات مصدر بيانات النموذج بالكامل أو استخدامها لتعديل المَعلمات غير المحدّدة، يُرجى الاطّلاع على الاستبدال مقابل التعديل.
`ds.alias.refreshFields`	اختياريّ. اضبط القيمة على `true` لاستخدام إعدادات مصدر البيانات المحدّدة من خلال Linking API من أجل إعادة تحميل حقول مصدر البيانات وتعديل مكوّنات التقرير باستخدام اختيارات الحقول الجديدة. يتم تحديد `true` عادةً عند تبديل نوع الموصل أو لأنواع الموصلات التي يؤدي فيها تغيير الإعداد إلى حقول مختلفة (على سبيل المثال، غالبًا ما تتغير حقول مصادر بيانات BigQuery مع إعدادات الجداول المختلفة). اضبط القيمة على `false` لترك حقول مصدر البيانات بدون تغيير من تقرير النموذج. يتم تحديد `false` عادةً عندما يؤدي إعداد البيانات الجديد إلى توفير الحقول نفسها بالضبط، وكنت تفضّل الاحتفاظ بأي تغييرات أجريتها على الحقول في مصدر بيانات النموذج. إذا لم يتم تحديدها، تختلف القيم التلقائية حسب نوع الموصل. راجِع مرجع الموصّل للاطّلاع على الإعدادات التلقائية الخاصة بالموصّل في حال أردت إلغاء السلوك التلقائي. نقاط يجب أخذها في الاعتبار عند استخدام `refreshFields`: إذا تم ضبط `refreshFields` على `false` وكان إعداد مصدر البيانات المحدّد من خلال Linking API يعرض حقولاً مختلفة عن الحقول المستخدَمة في التقرير النموذجي، من المحتمل أن يظهر للمستخدم خطأ في الإعداد للمكوّنات المتأثرة. إنّ التغييرات التي يتم إجراؤها على الحقول في مصدر بيانات النموذج (مثل الاسم والنوع والتجميع وما إلى ذلك) لا يتم نقلها إلى مصادر البيانات الجديدة عندما تكون قيمة `refreshFields` هي `true`. اضبط `refreshFields` على `false` للحفاظ على إعدادات الحقول من مصدر بيانات النموذج. سيتم دائمًا نسخ الحقول المحسوبة و المَعلمات المحدّدة في مصادر بيانات النماذج إلى مصادر البيانات التي تم إنشاؤها حديثًا، ولن تتأثر بقيمة `refreshFields`.
`ds.alias.connectorParameters`	مَعلمة مطلوبة. إعدادات مصدر البيانات لنوع الموصّل لمعرفة تفاصيل حول كيفية تحديد الموصّل المستخدَم لإنشاء مصدر بيانات، يُرجى الاطّلاع على نوع الموصّل. للحصول على تفاصيل حول مَعلمات مصدر البيانات المتاحة لكل نوع من أدوات الربط، اطّلِع على مرجع أدوات الربط.

الاستبدال مقابل التعديل - إعدادات مصدر البيانات

عند ضبط مَعلمات مصدر البيانات، يشير توفّر المَعلمة ds.connector في عنوان URL الخاص بـ Linking API أو عدم توفّرها إلى نية استبدال أو تعديل إعدادات مصدر بيانات النموذج، على التوالي.

يوضّح الجدول التالي كيف تؤثر المَعلمة ds.connector في ما إذا كان سيتم استبدال إعدادات مصدر بيانات النموذج بالكامل أو استخدامها لتعديل المَعلمات غير المحدّدة:

هل تم ضبط `ds.connector`؟	الإعداد والسلوك المتوقّعان	الاستخدام المعتاد
نعم	استبدال يتم استبدال إعدادات مصدر بيانات النموذج بالكامل، باستخدام مَعلمات مصدر البيانات المحدّدة في عنوان URL الخاص بواجهة Linking API. يجب تحديد جميع المَعلمات المطلوبة لنوع الموصل. اطّلِع على المَعلمات المطلوبة عند ضبط `ds.connector`.	عند تغيير نوع الموصّل لمصدر بيانات على سبيل المثال، إذا كنت قد أعددت مصدر بيانات BigQuery في التقرير النموذجي ولكنك تريد إعداد مصدر بيانات "جداول بيانات Google" من خلال Linking API. سيتطلّب ذلك تحديد إعدادات موصِّل جديدة بالكامل. عندما تريد ضمان إعداد مصدر بيانات. يؤدي استبدال الإعداد إلى تجنُّب استخدام أي قيم غير معروفة محتملة من مصدر بيانات النموذج.
لا	تعديل سيتم استخدام إعدادات مصدر بيانات النموذج لتحديد أي مَعلمات لم يتم توفيرها في عنوان URL الخاص بواجهة Linking API. جميع مَعلمات الوصلة الخاصة بنوع الوصلة اختيارية، ما لم يُذكر خلاف ذلك. يؤدي ذلك إلى تبسيط عنوان URL الخاص بواجهة Linking API، ويُنصح به بشكل عام عندما تكون على دراية بإعداد مصدر بيانات النموذج وتريد فقط تجاهل مجموعة فرعية من المَعلمات.	عندما تريد تقديم قيم المَعلمات التي تختلف عن مصدر بيانات النموذج فقط، ولا بأس لديك بالاعتماد على مصدر بيانات النموذج لأي مَعلمات موصّل غير محدّدة. على سبيل المثال، يمكنك تغيير رقم تعريف مشروع الفوترة لمصدر بيانات BigQuery فقط واستخدام إعدادات النموذج لجميع المَعلمات الأخرى.

المَعلمات المطلوبة عند ضبط `ds.connector`

في حال تحديد المَعلمة ds.connector لمصدر بيانات، يجب تحديد جميع مَعلمات الموصّل التي تم تصنيفها على أنّها مطلوبة لمصدر البيانات. إذا لم يتم تحديد المَعلمة ds.connector لمصدر البيانات، يمكن اعتبار جميع مَعلمات الموصل اختيارية، حتى تلك المحدّدة على أنّها مطلوبة، ما لم يُذكر خلاف ذلك.

أمثلة

تضبط هذه الطريقة تقريرًا باستخدام مصدر بيانات واحد من BigQuery (ds0) وتستبدل إعدادات مصدر البيانات بالكامل:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare

يمكن حذف الاسم المستعار لمصدر البيانات عندما يتضمّن التقرير مصدر بيانات واحدًا. يمكن تبسيط عنوان URL أعلاه إلى ما يلي:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.datasourceName=MyNewDataSource
  &ds.connector=bigQuery
  &ds.type=TABLE
  &ds.projectId=bigquery-public-data
  &ds.datasetId=samples
  &ds.tableId=shakespeare

يضبط هذا الإجراء تقريرًا باستخدام مصدر بيانات واحد من BigQuery (ds0) ويعدّل فقط رقم تعريف مشروع الفوترة لمصدر البيانات:

https://lookerstudio.google.com/reporting/create?
  c.reportId=12345
  &r.reportName=MyNewReport
  &ds.ds0.billingProjectId=my-billing-project

تضبط هذه الطريقة تقريرًا يتضمّن مصدرَي بيانات، وهما مصدر بيانات BigQuery (ds0) ومصدر بيانات "إحصاءات Google" (ds1). يتم استبدال إعدادات مصدر بيانات BigQuery بالكامل، بينما تعدّل إعدادات "إحصاءات Google" مَعلمة واحدة وتعتمد على مصدر بيانات النموذج ds1 لأي مَعلمات موصّل غير محدّدة:

https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &r.reportName=MyNewReportWithMultipleDataSources
  &ds.ds0.datasourceName=MyNewDataSource
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds1.viewId=92320289

الإنشاء في مقابل الإضافة

قد يكون من المفيد أحيانًا استخدام مصدر البيانات نفسه في تقارير متعددة، وذلك حتى تؤثّر التعديلات التي يتم إجراؤها على مصدر البيانات في جميع التقارير معًا. عند إنشاء تقرير باستخدام Linking API، يمكنك إعادة إضافة مصدر بيانات من تقرير النموذج الخاص بك من خلال التأكّد من استيفاء جميع الشروط التالية:

مصدر البيانات قابل لإعادة الاستخدام (راجِع مصادر البيانات المضمّنة مقابل مصادر البيانات القابلة لإعادة الاستخدام)
لا يشير عنوان URL إلى مصدر البيانات بالاسم المستعار
لا يستخدم عنوان URL اسمًا مستعارًا يتضمّن حرف بدل (راجِع حرف البدل للاسم المستعار لمصدر البيانات)

عند إنشاء مصدر بيانات جديد باستخدام Linking API، سيستخدم بيانات اعتماد المستخدم الذي نقر على عنوان URL. وهذا يعني أنّه يجب أن يكون لدى المستخدم إذن بالوصول إلى البيانات الأساسية وإلا لن يعمل الربط. من خلال إعادة إضافة مصدر البيانات إلى التقرير الذي تم إنشاؤه حديثًا، يمكنك الاحتفاظ ببيانات الاعتماد الخاصة به ليتمكّن المستخدمون من مواصلة الوصول إلى البيانات في تقاريرهم الجديدة.

حرف بدل لاسم مصدر البيانات البديل

لتطبيق مَعلمة Linking API على مصادر بيانات متعددة، يمكن استخدام الاسم المستعار لأحرف البدل ds.* بدلاً من الاسم المستعار لمصدر البيانات.

يمكن أن يكون ذلك مفيدًا لإزالة المَعلمات المتكرّرة من عنوان URL. على سبيل المثال، إذا كان لديك نموذج يتضمّن ثلاثة مصادر بيانات BigQuery مرفقة، وأردت استبدال projectId وdatasetId في كل مصدر، ولكن مع الاحتفاظ بـ tableId، يمكنك كتابة ذلك على النحو التالي:

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.ds1.projectId=client-project
  &ds.ds1.datasetId=client-dataset
  &ds.ds2.projectId=client-project
  &ds.ds2.datasetId=client-dataset
  &ds.ds3.projectId=client-project
  &ds.ds3.datasetId=client-dataset

أو باستخدام حرف البدل ds.*، يمكنك استخدام عنوان URL المكافئ التالي:

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset

تحظى المَعلمات المقدَّمة إلى Linking API التي لا تستخدم حرف البدل ds.* بالأولوية على المَعلمات التي تستخدمه. في المثال أعلاه، يمكنك إضافة اسم مستعار لمصدر بيانات محدّد لتجاهل القيمة من حرف البدل.

  https://lookerstudio.google.com/reporting/create?
  c.reportId=7890
  &ds.*.projectId=client-project
  &ds.*.datasetId=client-dataset
  &ds.ds1.datasetId=client-dataset

بشكلٍ عام، يكون ترتيب أولوية المَعلمات على النحو التالي:

مَعلمة مع اسم مستعار محدّد (ds.ds1.datasetId)
مَعلمة يتم توفيرها باستخدام حرف البدل (ds.*.datasetId)
قيمة مشتقة من مصدر بيانات النموذج، في حال عدم توفير ds.connector (راجِع الاستبدال مقابل التعديل)
القيمة التلقائية للمَعلمة، إذا كانت اختيارية

مرجع الموصّل

تتيح Linking API الموصلات والإعدادات التالية. لكل موصّل، يتم تقديم قائمة بمَعلمات مصدر البيانات المتاحة.

BigQuery

يتوافق موصّل BigQuery مع نوعَين من طلبات البحث، وهما TABLE، حيث تقدّم رقم تعريف الجدول الذي تريد البحث فيه، وCUSTOM_QUERY، حيث تقدّم عبارة SQL للبحث في جدول.

استعلامات TABLE

تنطبق المَعلمات التالية عندما يتم ضبط type على TABLE وتقدّم معرّف الجدول المطلوب البحث فيه.

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `bigQuery` لموصّل BigQuery. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات BigQuery المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.type`	مطلوبة** تحدّد هذه السمة نوع طلب البحث. اضبط القيمة على `TABLE`.
`ds.alias.projectId`	مطلوب** رقم تعريف المشروع الخاص بالجدول الذي سيتم تنفيذ طلب البحث فيه.
`ds.alias.datasetId`	مطلوب** معرّف مجموعة البيانات للجدول المطلوب الاستعلام عنه.
`ds.alias.tableId`	مطلوب** معرّف الجدول الذي سيتم الاستعلام عنه. الجداول المقسّمة حسب التاريخ: يمكن استخدام اللاحقة * (حرف بدل) أو `YYYYMMDD` عند الاستعلام عن الجداول المقسّمة حسب التاريخ. إذا تم تحديد جدول على أنّه "إحصاءات Google" أو "إحصاءات Firebase" أو Firebase Crashlytics، سيتم اختيار نموذج الحقول التلقائي ما لم يتم تحديد نموذج آخر. اطّلِع على المَعلَمات ذات الصلة بجدول نموذج الحقول.
`ds.alias.billingProjectId`	اختياريّ. معرّف المشروع الذي سيتم استخدامه للفوترة. في حال عدم ضبطها، سيتم استخدام `projectId`.
`ds.alias.isPartitioned`	اختياريّ. اضبط القيمة على `true` إذا كان الجدول مقسَّمًا وكنت تريد استخدام عمود التقسيم كسمة نطاق زمني. ينطبق ذلك فقط على التقسيم المستند إلى الوقت (مثل استخدام عمود تقسيم مستند إلى الوقت أو العمود الزائف `_PARTITIONTIME`) ولا يعمل مع الجداول المقسّمة حسب نطاق الأعداد الصحيحة. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. لمزيد من المعلومات، يُرجى الاطّلاع على مقدمة عن الجداول المقسّمة.
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

نموذج الحقول في "إحصاءات Google" و"إحصاءات Firebase" وCrashlytics

بالنسبة إلى الجداول التي تم تحديدها على أنّها "إحصاءات Google" أو Firebase Analytics أو Firebase Crashlytics، تتوفّر مَعلمات إضافية لضبط نموذج الحقول. إذا لم يتم تحديد نموذج، سيتم اختيار نموذج تلقائي.

الاسم	الوصف
`ds.alias.gaTemplateLevel`	اختياريّ. نموذج حقول "إحصاءات Google" المطلوب استخدامه. ينطبق ذلك فقط عند الاستعلام عن جدول BigQuery Export في "إحصاءات Google". إحدى القيم التالية: `ALL` أو `SESSION` أو `HITS` بالنسبة إلى جداول "إحصاءات Google"، يتم ضبط القيمة تلقائيًا على `ALL` في حال عدم تحديدها.
`ds.alias.firebaseTemplateLevel`	اختياريّ. نموذج حقول "إحصاءات Firebase" المطلوب استخدامه. ينطبق ذلك فقط عند طلب البحث عن جدول BigQuery Export في "إحصاءات Firebase". يمكن ضبطه على `EVENTS` فقط. بالنسبة إلى جداول "إحصاءات Firebase"، يتم ضبط القيمة تلقائيًا على `EVENTS` في حال عدم تحديد أي قيمة.
`ds.alias.crashlyticsTemplateLevel`	نموذج حقول Firebase Crashlytics المطلوب استخدامه يمكن ضبطها على `DEFAULT` فقط. ينطبق ذلك فقط عند طلب البحث عن جدول BigQuery Export الخاص بـ Firebase Crashlytics. بالنسبة إلى جداول Firebase Crashlytics، يتم ضبط القيمة تلقائيًا على `DEFAULT` في حال عدم تحديدها.

طلبات البحث المخصّصة

تنطبق المَعلمات التالية عندما يتم ضبط type على CUSTOM_QUERY وتقدّم عبارة SQL للاستعلام عن جدول.

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `bigQuery` لموصل BigQuery. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات BigQuery المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.type`	مطلوبة** تحدّد هذه السمة نوع طلب البحث. اضبط القيمة على `CUSTOM_QUERY`.
`ds.alias.sql`	مطلوب** استعلام SQL المطلوب تنفيذه.
`ds.alias.billingProjectId`	اختياريّ. معرّف المشروع الذي سيتم استخدامه للفوترة. في حال عدم ضبطها، سيتم استخدام `projectId`. في حال عدم ضبط `projectId`، سيتم استخدام مشروع الجدول الذي تم الاستعلام عنه.
`ds.alias.sqlReplace`	اختياريّ. قائمة بأنماط وسلاسل استبدال مفصولة بفواصل يجب تطبيقها على طلب بحث SQL. لا يتم استبدال السلسلة إلا إذا كان هناك تطابق مع النمط. استخدِم فاصلة للفصل بين أزواج السلسلة النموذجية وسلسلة الاستبدال. مثلاً: `stringPattern1,replacementString1, stringPattern2,replacementString2`
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

أمثلة

إعداد من النوع TABLE يتم فيه تحديد طلب البحث باستخدام معرّف جدول:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=shakespeare
  &ds.ds0.billingProjectId=myProject

إعداد نوع TABLE لطلب البحث في جدول مقسّم حسب التاريخ باستخدام لاحقة أحرف البدل:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_*

إعداد النوع TABLE لطلب البحث في جدول مقسّم حسب التاريخ باستخدام اللاحقة YYYYMMDD:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=price-data
  &ds.ds0.datasetId=samples
  &ds.ds0.tableId=stock_YYYYMMDD

إعداد من النوع TABLE لطلب البحث عن جدول BigQuery Export في "إحصاءات Google"، باستخدام نموذج الحقول SESSION:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=my-gabq-project
  &ds.ds0.datasetId=1234567
  &ds.ds0.tableId=ga_sessions_YYYYMMDD
  &ds.ds0.gaTemplateLevel=SESSION

إعداد من النوع TABLE لطلب البحث عن جدول مقسّم حسب وقت الاستيعاب واستخدام عمود التقسيم كسمة نطاق زمني:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=TABLE
  &ds.ds0.projectId=acme-co-logs
  &ds.ds0.datasetId=logs
  &ds.ds0.tableId=logs_table
  &ds.ds0.isPartitioned=true

إعداد من النوع CUSTOM_QUERY يتم فيه تحديد طلب البحث باستخدام عبارة SQL:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.connector=bigQuery
  &ds.ds0.type=CUSTOM_QUERY
  &ds.ds0.projectId=bigquery-public-data
  &ds.ds0.sql=SELECT%20word%2C%20word_count%20FROM%20%60bigquery-public-data.samples.shakespeare%60
  &ds.ds0.billingProjectId=myProject

إعدادات النوع CUSTOM_QUERY التي يتم فيها تعديل عبارة SQL فقط ويتم استخدام مصدر بيانات النموذج لبقية الإعدادات:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sql=SELECT%20corpus%20FROM%20%60bigquery-public-data.samples.shakespeare%60

إعدادات النوع CUSTOM_QUERY حيث يتم تعديل عبارة SQL الخاصة بمصدر بيانات النموذج باستخدام sqlReplace:

https://lookerstudio.google.com/reporting/create?
  c.reportId=123abc
  &ds.ds0.sqlReplace=bigquery-public-data,new-project,samples,new-dataset

# The following shows a template query before and after sqlReplace is applied.
#
# Template data source custom query:
#   SELECT word, word_count FROM big-query-public-data.samples.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM big-query-public-data.samples.raleigh
#
# New data source custom query with sqlReplace applied:
#   SELECT word, word_count FROM new-project.new-dataset.shakespeare
#   INNER JOIN
#   SELECT word, word_count FROM new-project.new-dataset.raleigh

Cloud Spanner

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `cloudSpanner` من أجل موصل Cloud Spanner. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات Cloud Spanner المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.projectId`	مطلوب** رقم تعريف المشروع.
`ds.alias.instanceId`	مطلوب** معرّف الجهاز الافتراضي.
`ds.alias.databaseId`	مطلوب** رقم تعريف قاعدة البيانات
`ds.alias.sql`	مطلوب** استعلام SQL المطلوب تنفيذه.
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

مثال

إعداد Cloud Spanner مع عبارة SQL:

https://lookerstudio.google.com/reporting/create?
  c.reportId=456def
  &ds.ds1.connector=cloudSpanner
  &ds.ds1.projectId=myProject
  &ds.ds1.instanceId=production
  &ds.ds1.datasetId=transactions
  &ds.ds1.sql=SELECT%20accountId%2C%20date%2C%20revenue%20FROM%20sales%3B

موصّلات بيانات من إنشاء المنتدى

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `community` لـ موصّل Community Connector. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات Community Connector المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.connectorId`	مطلوب** أداة ربط Community `connectorId` (المعروفة أيضًا باسم `deploymentId`).
`ds.alias.parameters`	اختياريّ. مَعلمات إضافية خاصة بالموصل، كما هو محدّد في إعدادات الموصل الخاصة بالموصل الذي أنشأه المنتدى.
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

مثال

اتّصِل بموصّل بيانات من إنشاء المنتدى باستخدام مَعلمات الإعداد state وcity:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=community
  &ds.ds5.connectorId=AqwqXxQshl94nJa0E0-1MsZXQL0DfCsJIMWk7dnx
  &ds.ds5.state=CA
  &ds.ds5.city=Sacramento

إحصاءات Google

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `googleAnalytics` من أجل أداة ربط "إحصاءات Google". في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات "إحصاءات Google" المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.accountId`	مطلوب** رقم تعريف الحساب.
`ds.alias.propertyId`	مطلوب** رقم تعريف الموقع
`ds.alias.viewId`	معرّف الملف الشخصي. مطلوب** لمواقع Universal Analytics. لا تضبط هذا الحقل لمواقع "إحصاءات Google‏ 4".
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

أمثلة

إعدادات "إحصاءات Google" لموقع على Universal Analytics:

https://lookerstudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=UA-54516992-1
  &ds.ds2.viewId=92320289

إعدادات "إحصاءات Google" لموقع على "إحصاءات Google‏ 4":

https://lookerstudio.google.com/reporting/create?
  c.reportId=789ghi
  &ds.ds2.connector=googleAnalytics
  &ds.ds2.accountId=54516992
  &ds.ds2.propertyId=213025502

Google Cloud Storage

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `googleCloudStorage` أداة ربط Google Cloud Storage. في حال ضبطها، تحلّ محل مصدر البيانات باستخدام إعدادات Google Cloud Storage المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.pathType`	مطلوبة** تحدّد هذه السمة نوع المسار. استخدِم `FILE` لاختيار ملف واحد أو `FOLDER` لاختيار جميع الملفات للمسار المحدّد.
`ds.alias.path`	مطلوب** مسار الملف (مثل MyBucket/MyData/MyFile.csv) إذا كانت قيمة `pathType` هي `FILE` أو مسار المجلد (مثل *MyBucket/MyData) إذا كانت قيمة `pathType` هي `FOLDER`.
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

مثال

إعداد Google Cloud Storage لملف واحد:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FILE
  &ds.ds50.path=MyBucket%2FMyData%2FMyFile.csv

إعداد Google Cloud Storage لجميع الملفات في المسار:

https://lookerstudio.google.com/reporting/create?
  c.reportId=231908kpf
  &ds.ds50.connector=googleCloudStorage
  &ds.ds50.pathType=FOLDER
  &ds.ds50.path=MyBucket%2FMyData

جداول بيانات Google

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `googleSheets` لموصل جداول بيانات Google. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات "جداول بيانات Google" المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.spreadsheetId`	مطلوب** معرّف جدول البيانات.
`ds.alias.worksheetId`	مطلوب** معرّف ورقة العمل.
`ds.alias.hasHeader`	اختياريّ. اضبط القيمة على `true` لاستخدام الصف الأول كعناوين. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. يجب أن تكون عناوين الأعمدة فريدة. لن تتم إضافة الأعمدة التي تتضمّن عناوين فارغة إلى مصدر البيانات.
`ds.alias.includeHiddenCells`	اختياريّ. اضبط القيمة على `true` لتضمين الخلايا المخفية. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها.
`ds.alias.includeFilteredCell`	اختياريّ. اضبط القيمة على `true` لتضمين الخلايا التي تمت فلترتها. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها.
`ds.alias.range`	اختياريّ. النطاق، مثل A1:B52
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `true` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

أمثلة

إعدادات "جداول بيانات Google":

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437

إعدادات "جداول بيانات Google" مع استخدام الصف الأول كعناوين وتضمين الخلايا المخفية والمصفّاة:

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.hasHeader=true
  &ds.ds3.includeHiddenCells=true
  &ds.ds3.includeFilteredCells=true

إعدادات "جداول بيانات Google" مع نطاق (A1:D20):

https://lookerstudio.google.com/reporting/create?
  c.reportId=101112jkl
  &ds.ds3.connector=googleSheets
  &ds.ds3.spreadsheetId=1Qs8BdfxZXALh6vX4zrE7ZyGnR3h5k
  &ds.ds3.worksheetId=903806437
  &ds.ds3.range=A1%3AD20

Looker

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `looker` لموصّل Looker. في حال ضبطها، يتم استبدال مصدر البيانات بإعدادات Looker المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.instanceUrl`	مطلوب** عنوان URL لنسخة Looker.
`ds.alias.model`	مطلوب** نموذج Looker
`ds.alias.explore`	مطلوب** استكشاف Looker
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

مثال

الربط بميزة "استكشاف" في Looker:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=looker
  &ds.ds5.instanceUrl=my.looker.com
  &ds.ds5.model=thelook
  &ds.ds5.explore=orders

Search Console

اسم المعلَمة	الوصف
`ds.alias.connector`	اختياريّ. اضبط القيمة على `searchConsole` من أجل أداة ربط البيانات في Search Console. في حال ضبط هذا الخيار، سيتم استبدال مصدر البيانات بإعدادات Search Console المقدَّمة. اطّلِع على الفرق بين الاستبدال والتعديل.
`ds.alias.siteUrl`	مطلوب** عنوان URL للموقع الإلكتروني. بالنسبة إلى موقع إلكتروني على النطاق، يجب إضافة البادئة `sc-domain\:`.
`ds.alias.tableType`	مطلوبة** تحدّد نوع الجدول. يمكن أن تكون القيمة إحدى القيمتين `SITE_IMPRESSION` أو `URL_IMPRESSION`.
`ds.alias.searchType`	مطلوبة** تحدّد نوع البحث. يمكن أن تكون إحدى القيم التالية: `WEB` أو `IMAGE` أو `VIDEO` أو `NEWS`.
`ds.alias.refreshFields`	اختياريّ. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. لمزيد من التفاصيل، يُرجى الاطّلاع على refreshFields.

مثال

إعدادات موقع يحمل بادئة عنوان URL على Search Console:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  &ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=https%3A%2F%2Fwww.example.com%2Fwelcome
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

إعدادات موقع إلكتروني على نطاق في Search Console:

https://lookerstudio.google.com/reporting/create?
  c.reportId=161718pqr
  ds.ds5.connector=searchConsole
  &ds.ds5.siteUrl=sc-domain%3Aexample.com
  &ds.ds5.tableType=SITE_IMPRESSION
  &ds.ds5.searchType=WEB

أذونات النماذج

لضمان تقديم أفضل تجربة للمستخدمين، من المهم ضبط أذونات الوصول إلى التقارير بشكل صحيح لتقرير النموذج ومصادر البيانات المرتبطة به. تعتمد الأذونات المطلوبة على ما إذا كان نموذج التقرير يستخدم مصادر بيانات مضمّنة أو قابلة لإعادة الاستخدام وما إذا كان إعداد Linking API مضبوطًا على استبدال أو تعديل إعداد مصدر بيانات.

يوضّح الجدول التالي إذن الوصول المقترَح إلى مصدر البيانات للحصول على أفضل تجربة للمستخدم استنادًا إلى مصادر بيانات النموذج وإعدادات Linking API:

نوع مصدر البيانات	ربط إعدادات واجهة برمجة التطبيقات بمصدر البيانات	اقتراح بشأن أذونات مصدر البيانات	ملاحظات
تاريخ التضمين	استبدال	لا ينطبق - سيتم اكتساب الإذن بالاطّلاع من التقرير.	إذا كان لدى المستخدم إذن بالاطّلاع على تقرير النموذج، سيتم تلقائيًا منحه إذنًا بالاطّلاع على أي مصدر بيانات مضمّن.
تاريخ التضمين	تعديل	لا ينطبق - سيتم اكتساب الإذن بالاطّلاع من التقرير.	إذا كان لدى المستخدم إذن بالاطّلاع على تقرير النموذج، سيتم تلقائيًا منحه إذنًا بالاطّلاع على أي مصدر بيانات مضمّن.
قابلة لإعادة الاستخدام	استبدال	لا يحتاج المستخدمون إلى إذن بالاطّلاع.	بما أنّه سيتم استبدال إعدادات مصدر البيانات بالكامل من خلال Linking API، لن يكون الإذن بالاطّلاع مطلوبًا.
قابلة لإعادة الاستخدام	تعديل	يجب أن يكون لدى المستخدمين إذن بالاطّلاع.	يجب توفُّر الإذن بالاطّلاع على مصدر البيانات كي تتمكّن Linking API من قراءة الإعدادات واستخدامها من مصدر بيانات النموذج. إذا لم يكن لدى المستخدمين الإذن بالاطّلاع، ستظهر لهم رسالة خطأ عند تحميل التقرير.

استخدام تقرير فارغ أو تلقائي

لاستخدام تقرير فارغ أو التقرير التلقائي، اضبط واجهة Linking API على النحو التالي:

نوع التقرير ضبط مَعلمة التحكّم reportId اضبط مَعلمات مصدر البيانات (ds). ملاحظات

تقرير فارغ لا لا

التقرير التلقائي

لا

نعم

نوع التقرير	ضبط مَعلمة التحكّم `reportId`	اضبط مَعلمات مصدر البيانات (`ds`).	ملاحظات
تقرير فارغ	لا	لا
التقرير التلقائي	لا	نعم	يوفّر "مركز البيانات" التقرير التلقائي. لا يُشترط استخدام اسم مستعار لمصدر البيانات عند تحديد مَعلمات مصدر البيانات للتقرير التلقائي، لأنّ التقرير التلقائي يتضمّن مصدر بيانات واحدًا مضمّنًا.

يوفّر "مركز البيانات" التقرير التلقائي.

لا يُشترط استخدام اسم مستعار لمصدر البيانات عند تحديد مَعلمات مصدر البيانات للتقرير التلقائي، لأنّ التقرير التلقائي يتضمّن مصدر بيانات واحدًا مضمّنًا.

تعرض الأمثلة التالية عناوين URL مختلفة لواجهة Linking API تستخدم تقريرًا فارغًا أو تلقائيًا.

ابدأ سير عمل إنشاء التقرير بتقرير فارغ:

https://lookerstudio.google.com/reporting/create

ابدأ سير عمل إنشاء التقرير بتقرير فارغ واضبط اسم التقرير:

https://lookerstudio.google.com/reporting/create?r.reportName=MyNewReport

استخدِم نموذج التقرير التلقائي مع إعدادات موصّل "جداول بيانات Google":

https://lookerstudio.google.com/reporting/create?
  ds.connector=googleSheets
  &ds.spreadsheetId=1Q-w7KeeJj1jk3wFcFm4NsPlppNscs0CtHf_EP9fsYOo
  &ds.worksheetId=0

تضمين تقرير

لتضمين تقرير تم إنشاؤه باستخدام Linking API، اضبط مَعلمات عنوان URL وأدرِج المسار /embed/. يجب أن يكون عنوان URL المضمّن لواجهة Linking API بالشكل التالي:

https://lookerstudio.google.com/embed/reporting/create?parameters

العثور على أرقام التعريف والأسماء المستعارة

معرّف التقرير

للعثور على رقم تعريف التقرير، اتّبِع الخطوات التالية:

افتح التقرير الذي تريد استخدامه كنموذج. يُرجى فحص عنوان URL الخاص بالتقرير. الجزء بين reporting/ و/page هو رقم تعريف التقرير. على سبيل المثال، في عنوان URL التالي، 0B_U5RNpwhcE6SF85TENURnc4UjA هو معرّف التقرير:

https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M

شريط عناوين المتصفح يعرض عنوان URL لتقرير في "مركز البيانات".
تم تمييز رقم تعريف التقرير. — ابحث عن معرّف البلاغ في عنوان URL الخاص بالتقرير.

الاسم المستعار لمصدر البيانات

يمكن أن يتضمّن التقرير عدة مصادر بيانات. يجب الإشارة إلى مصدر البيانات باستخدام الاسم المستعار.

للعثور على اسم مستعار لمصدر بيانات، اتّبِع الخطوات التالية:

عدِّل التقرير.
من شريط الأدوات، انقر على المورد > إدارة مصادر البيانات المضافة.
راجِع عمود الاسم المستعار للعثور على معلومات الاسم المستعار لكل مصدر بيانات.

يمكنك تعديل أسماء الأسماء المستعارة لضمان التوافق مع الإصدارات القديمة عند إضافة مصدر بيانات أو إزالته.

قائمة بمصادر البيانات في صفحة إدارة موارد "مصدر البيانات"
يتم تمييز عمود "الاسم المستعار". — ابحث عن الاسم المستعار لمصدر البيانات في صفحة إدارة *مصادر البيانات*.

نوع الموصّل

يمكن أن يتضمّن التقرير عدّة مصادر بيانات، يتم إنشاء كلّ منها من خلال ضبط أحد الموصلات. للعثور على نوع الموصّل المستخدَم لإنشاء مصدر بيانات:

عدِّل التقرير.
من شريط الأدوات، انقر على المورد > إدارة مصادر البيانات المضافة.
راجِع عمود نوع الموصّل لتحديد الموصّل المستخدَم لإنشاء مصدر بيانات.

قائمة بمصادر البيانات في صفحة إدارة موارد "مصدر البيانات"
يتم تمييز عمود "نوع الموصّل". — ابحث عن نوع أداة ربط مصدر البيانات في صفحة إدارة *مصادر البيانات*.

تحديد المشاكل وحلّها ونصائح ذات صلة

إذا كنت تواجه مشكلة، راجِع التفاصيل أدناه لتحديد المشاكل المحتملة والإعدادات الخاطئة الشائعة.

مربّع حوار تصحيح الأخطاء

استخدِم مربّع الحوار الخاص بتصحيح الأخطاء لمراجعة إعدادات Linking API كما يفسّرها مركز البيانات. يمكن أن يساعد ذلك في تصحيح الأخطاء في واجهة برمجة التطبيقات.

عند حدوث خطأ أثناء تحليل عنوان URL الخاص بواجهة Linking API، سيظهر تلقائيًا مربّع حوار يتضمّن تفاصيل حول الخطأ.
عند حدوث خطأ وعدم ظهور أي مربّع حوار تلقائيًا، ابحث عن زر المعلومات في أعلى يسار التقرير. انقر للحصول على معلومات إضافية عن تصحيح الأخطاء.
في حال عدم توفّر زر المعلومات، يمكنك تفعيله من خلال إضافة المَعلمة &c.explain=true إلى نهاية أي عنوان URL لواجهة Linking API.

الأذونات

تأكَّد من ضبط أذونات النموذج الصحيحة لأنواع مصادر البيانات وإعدادات Linking API. راجِع مقالة أذونات النماذج للحصول على التفاصيل.

التعديل في مقابل الاستبدال

في حال تعديل إعدادات مصدر بيانات من نموذج مصدر بيانات، راجِع إعدادات مصدر البيانات في النموذج وإعدادات Linking API للتأكّد من توافقهما. تأكَّد من أنّ الحقول الناتجة من الإعداد الجديد متوافقة مع مكوّنات التقرير وإعداده.

عند إجراء عملية تعديل بدلاً من الاستبدال، من المحتمل ضبط إعداد غير صالح مع سلوك غير محدّد. يمكنك الاطّلاع على مقالة الاستبدال مقابل التعديل لمعرفة التفاصيل.

إعادة تحميل الحقول

إذا كنت قد أعددت أسماء الحقول أو أنواعها أو عمليات التجميع لمصدر بيانات نموذج، لن يتم نقل هذه التغييرات إلى مصدر بيانات تم إعداده باستخدام Linking API إلا إذا تم ضبط المَعلمة ds.refreshFields على false.

راجِع مَعلمة مصدر البيانات ds.refreshFields الخاصة بعنوان URL لواجهة Linking API. في حال حذفها، تأكَّد من أنّ القيمة التلقائية للمَعلمة لكل نوع من أنواع الموصلات صحيحة لحالة الاستخدام.

بشكل عام، إذا كنت قد أعددت الحقول في مصدر بيانات النموذج وكنت متأكدًا من أنّ إعدادات مصدر البيانات الجديدة من خلال Linking API ستؤدي دائمًا إلى الحقول نفسها بالضبط، ننصحك بضبط refreshFields على false.

على سبيل المثال، إذا حدّد Data Studio أثناء إنشاء نموذج تقرير أنّ حقل مصدر بيانات معيّن هو من النوع رقم، ثم غيّرته إلى النوع سنة، سيصبح تغيير إعدادات هذا الحقل جزءًا من مصدر بيانات النموذج. أي رسم بياني في نموذج التقرير يستخدم الحقل المعدَّل سيتطلّب سنة، وإذا كان الرسم البياني يستند إلى الوقت، قد لا يتم عرضه بخلاف ذلك. في حال استخدام Linking API لتوفير إعدادات جديدة لمصدر البيانات تؤدي إلى ظهور الحقول نفسها بالضبط، ستكون هناك نتيجتان استنادًا إلى قيمة المَعلمة refreshFields:

إذا تم ضبطها على true، لن يتم نقل إعدادات الحقل من مصدر بيانات النموذج، وقد يتعذّر تحميل الرسوم البيانية إذا كانت تعتمد على إعدادات الحقل نفسها (أي أنّه من المتوقّع توفّر حقل من النوع Year).
إذا تم ضبطها على false، سيتم نقل إعدادات الحقول من مصدر بيانات النموذج إلى مصدر البيانات الجديد، وستتلقّى الرسوم البيانية للتقارير الحقول نفسها مع الإعدادات نفسها وسيتم تحميلها بنجاح.

الملاحظات والدعم

استخدِم Issue Tracker للإبلاغ عن مشاكل في Linking API أو لتقديم ملاحظات. يمكنك الاطّلاع على الدعم للحصول على مراجع عامة حول الحصول على المساعدة وطرح الأسئلة.

سجلّ التغييرات

2023-06-06

تمّت إضافة مَعلمتَي التقرير r.measurementId وr.keepMeasurementId لإعداد خيار التقرير أرقام تعريف القياس في "إحصاءات Google".
تمت إضافة ds.keepDatasourceName للتحكّم في إعادة استخدام اسم مصدر بيانات النموذج.
تمت إضافة قسم تضمين تقرير.
أداة ربط BigQuery
- تمت إضافة sqlReplace. تتيح لك تحديد أنماط وسلاسل استبدال لتعديل طلب بحث SQL الخاص بمصدر بيانات النموذج.

2023-05-22

تمت إضافة إمكانية استخدام موصّل Looker.
تمت إضافة إمكانية استخدام وصلات خارجية.

2022-11-21

تمت إضافة إمكانية استخدام تقرير فارغ. راجِع مقالة استخدام تقرير فارغ أو تلقائي
تمت إضافة قسم refreshFields إلى تحديد المشاكل وحلّها ونصائح ذات صلة.

2022-11-14

تمت إزالة مرجع موصّل "استطلاعات Google" بسبب إيقاف "استطلاعات Google" نهائيًا.

2022-06-15

انتهاء الفترة التجريبية
- تمت إعادة تسمية Integration API إلى Linking API.
- أصبح الإصدار الكامل من Linking API متاحًا.
تمت إضافة مَعلمة التحكّم pageId للسماح بالربط بصفحة تقرير معيّنة.
تمت إضافة مَعلمة عنصر التحكّم mode لضبط حالة التقرير على وضع العرض أو التعديل عند التحميل.
يمكن الآن استبدال إعدادات مصادر البيانات بالكامل أو تعديلها جزئيًا. ويتم تحديد هذا السلوك من خلال ما إذا تم ضبط المَعلمة ds.connector. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة الاستبدال مقابل التعديل.
يتم الآن استخدام نموذج تلقائي إذا لم يتم توفير نموذج تقرير باستخدام المَعلمة c.reportId.
تمّت إضافة مَعلمة مصدر البيانات ds.refreshFields. يتيح لك ذلك التحكّم في ما إذا كان سيتم إعادة تحميل حقول مصدر البيانات عند تحميل إعدادات مصدر البيانات.
أداة ربط BigQuery
- لا تكون السمة projectId مطلوبة عندما تكون السمة type مضبوطة على CUSTOM_QUERY.
- في حال عدم ضبط billingProjectId، سيتم استخدام projectId أو مشروع الجدول الذي تم الاستعلام عنه كخيار احتياطي لمشروع الفوترة.
- تمت إضافة إمكانية استخدام الجداول المقسّمة حسب التاريخ. اضبط المَعلمة isPartitioned على true لاستخدام حقل التقسيم كسمة نطاق زمني.
- تمت إضافة إمكانية طلب البحث عن الجداول المقسَّمة حسب التاريخ باستخدام حرف البدل أو لاحقة الجدول YYYYMMDD.
- تمّت إضافة إمكانية طلب البحث في جداول "إحصاءات Google" أو "إحصاءات Firebase" أو Crashlytics واختيار نموذج حقول.
جداول بيانات Google
- يتم ضبط قيمة hasHeader تلقائيًا على true، بما يتوافق مع الإعداد التلقائي لواجهة مستخدم الويب.
- تم تقسيم includeHiddenAndFilteredCell إلى includeHiddenCells و
- includeFilteredCells، وكلاهما يستخدمان الآن true تلقائيًا، بما يتوافق مع الإعداد التلقائي لواجهة المستخدم على الويب.
أداة ربط البيانات في Search Console
- تمت إعادة تسمية المَعلمة propertyType إلى searchType.
أداة ربط الاستطلاعات
- تقبل السمة surveyId الآن رقم تعريف استطلاع واحدًا أو قائمة بأرقام تعريف الاستطلاعات مفصولة بفواصل.

2021-12-16

الإصدار الأولي من Integration API
- يتيح الربط بتقرير حالي وتحديد اسم التقرير.
- يمكن ضبط مصادر بيانات متعددة وتحديد اسم لكل مصدر بيانات.
- إتاحة أنواع الموصّلات التالية: BigQuery وCloud Spanner و"إحصاءات Google" وGoogle Cloud Storage و"جداول بيانات Google" و"استطلاعات Google" وSearch Console

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

مقدمة

حالة الاستخدام والمزايا

آلية العمل

سير عمل المطوّر لواجهة Linking API

تجربة المستخدم في ربط حسابات واجهة برمجة التطبيقات

المتطلبات

معلمات عنوان URL

مَعلمات التحكّم

مَعلمات التقرير

مَعلمات مصدر البيانات

مَعلمات مصدر البيانات

الاستبدال مقابل التعديل - إعدادات مصدر البيانات

المَعلمات المطلوبة عند ضبط ds.connector

أمثلة

الإنشاء في مقابل الإضافة

حرف بدل لاسم مصدر البيانات البديل

مرجع الموصّل

BigQuery

استعلامات TABLE

نموذج الحقول في "إحصاءات Google" و"إحصاءات Firebase" وCrashlytics

طلبات البحث المخصّصة

Cloud Spanner

موصّلات بيانات من إنشاء المنتدى

إحصاءات Google

Google Cloud Storage

جداول بيانات Google

Looker

Search Console

أذونات النماذج

استخدام تقرير فارغ أو تلقائي

تضمين تقرير

العثور على أرقام التعريف والأسماء المستعارة

معرّف التقرير

الاسم المستعار لمصدر البيانات

نوع الموصّل

تحديد المشاكل وحلّها ونصائح ذات صلة

مربّع حوار تصحيح الأخطاء

الأذونات

التعديل في مقابل الاستبدال

إعادة تحميل الحقول

الملاحظات والدعم

سجلّ التغييرات

2023-06-06

2023-05-22

2022-11-21

2022-11-14

2022-06-15

2021-12-16

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

المَعلمات المطلوبة عند ضبط `ds.connector`