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

مقدمة

توفّر واجهة برمجة تطبيقات الربط واجهة موثوقة لإعداد المستخدمين وإعادة توجيههم مباشرةً إلى تقرير Looker Studio من خلال عنوان URL. عندما يتّبع المستخدمون عنوان URL لربط واجهة برمجة التطبيقات، ستتوفّر لهم تجربة مبسّطة لعرض بياناتهم والتفاعل معها بسرعة.

يصف هذا المستند التنسيق المطلوب لربط عناوين URL لواجهة برمجة التطبيقات والمعلمات المتاحة.

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

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

• تجربة إنشاء التقارير بنقرة واحدة لعملائك:
  • تتوفّر إعدادات البيانات في عنوان URL كي لا يحتاج المستخدمون إلى ضبط التقرير لبياناتهم.
  • يمكن للمستخدمين حفظ التقرير بنقرة واحدة وإعادة الانتقال إلى التقرير في أي وقت.
• إنشاء التقارير على نطاق واسع: تعمل واجهة برمجة التطبيقات للربط على تقليل الوقت المطلوب لتكرار أو إنشاء تقارير جديدة.
• تفعيل عمليات دمج المنتجات: تسمح لك الواجهة الثابتة بدمج Looker Studio في سير عمل المنتج.

آلية العمل

في ما يلي شرح لكيفية تفاعل المطوّرين والمستخدمين مع ربط واجهة برمجة التطبيقات.

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

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

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

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

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

1. في المتصفح، يزور المستخدم خدمة مدمَجة مع ربط واجهة برمجة التطبيقات.
2. تدعو عبارة الحث على اتّخاذ إجراء المستخدِم إلى النقر على رابط لعرض بياناته في Looker Studio.
3. يتّبع المستخدم الرابط ويتم توجيهه إلى تقرير Looker Studio. يتم تحميل التقرير ويتمكن المستخدم من عرض بياناته والتفاعل معها.
4. ينقر المستخدم على "تعديل ومشاركة". يتم حفظ التقرير في حسابه على Looker Studio.
5. يتمتع المستخدم الآن بإمكانية الوصول الكامل والتحكم في نسخته الخاصة من التقرير. ويمكنهم العرض والتعديل والمشاركة في أي وقت.

المتطلّبات

لضمان عمل عنوان URL لواجهة برمجة التطبيقات للربط كما هو متوقع، يجب توفير ما يلي:

1. تقرير، ليكون نموذجًا. وفي حال عدم توفيرها، يمكن استخدام تقرير فارغ أو تقرير تلقائي من Looker Studio.
2. يجب أن يحصل مستخدمو عنوان URL لواجهة برمجة التطبيقات للربط على الأقل على الإذن بالاطّلاع على تقرير النموذج. واعتمادًا على نوع مصادر البيانات المستخدَمة في التقرير والإعدادات التي يتم توفيرها من خلال واجهة برمجة تطبيقات الربط، قد يطلب المستخدمون أيضًا الإذن بالاطّلاع على مصادر البيانات. يمكنك الاطّلاع على أذونات النموذج لمعرفة التفاصيل.
3. يجب أن يتيح نوع الموصّل لكل مصدر بيانات إمكانية الضبط من خلال واجهة برمجة تطبيقات الربط. يمكنك الرجوع إلى مرجع الموصل للحصول على قائمة بالموصلات المتوافقة.
4. يجب أن يتمكّن مستخدمو عنوان URL لواجهة برمجة تطبيقات الربط من الوصول إلى البيانات التي تم ضبطها في عنوان URL لواجهة برمجة التطبيقات للربط. إذا لم يكن للمستخدم حق الوصول إلى البيانات الأساسية، فسيتم عرض خطأ في أي مكونات تقارير تابعة.

ملاحظة: لا تغيِّر واجهة برمجة التطبيقات Linking API إمكانية الوصول إلى البيانات الحالية أو إعدادات المشاركة أو نموذج التقرير الأصلي وإعدادات مصادر البيانات.

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

يجب أن يكون عنوان URL لواجهة برمجة التطبيقات للربط على النحو التالي:

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

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

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

في ما يلي مثال على ربط عنوان URL لواجهة برمجة التطبيقات. تم ضبط اسم التقرير وضبط مصدر بيانات 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 صالح، يُرجى الاطّلاع على ترميز عناوين URL.

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

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

تحدد معلمات التحكم حالة التقرير عند عرضه من خلال عنوان URL لواجهة برمجة التطبيقات للربط.

اسم المعلَمة	الوصف
c.reportId	اختياريّ. رقم تعريف تقرير النموذج سيتم فتح أداة Looker Studio وإعداد التقرير المحدّد. للحصول على تفاصيل حول كيفية العثور على المعرّف، راجع معرّف البلاغ. وفي حال عدم تحديد هذا الحقل، سيتم استخدام تقرير فارغ أو نموذج تقرير تلقائي، ويمكنك الاطّلاع على استخدام تقرير فارغ أو تلقائي للتفاصيل.
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 لضبط رقم التعريف.

مثال

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، يُرجى الاطّلاع على العنوان البديل لمصدر البيانات.

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

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

المعلمات التالية شائعة في جميع أنواع الموصلات:

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

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

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

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

هل تم ضبط "ds.connector"؟	التكوين والسلوك المتوقعان	معدّل الاستخدام المعتاد
نعم	استبدال: يتم استبدال إعدادات مصدر بيانات النموذج بالكامل، باستخدام مَعلمات مصدر البيانات المحدّدة في عنوان URL لواجهة برمجة تطبيقات الربط. عليك تحديد جميع المعلَمات المطلوبة لنوع الموصل. راجِع المَعلمات المطلوبة عند ضبط ds.connector.	عند تغيير نوع الموصِّل لمصدر البيانات. على سبيل المثال، إذا ضبطت مصدر بيانات BigQuery في تقرير النماذج ولكنك تريد ضبط مصدر بيانات "جداول بيانات Google" من خلال Linking API. سيتطلب ذلك ضبط إعدادات موصِّل جديدة. عندما تريد ضمان ضبط مصدر البيانات. يتجنّب استبدال الإعدادات أي قيم غير معروفة يُحتمل استخدامها من مصدر بيانات النموذج.
لا	تحديث. سيتم استخدام إعدادات مصدر بيانات النموذج لتحديد أي معلَمات لم يتم توفيرها في عنوان URL لواجهة برمجة تطبيقات الربط. جميع معلَمات الموصِّل لنوع الموصل اختيارية، ما لم يُذكر خلاف ذلك. يساهم هذا الإجراء في تبسيط عنوان URL لواجهة برمجة التطبيقات للربط، وننصح به بشكل عام عندما تكون على دراية بإعدادات مصدر بيانات النموذج وتريد إلغاء مجموعة فرعية من المَعلمات فقط.	عندما تريد فقط تقديم قيم مَعلمات تختلف عن مصدر بيانات النموذج، ولا مشكلة في الاعتماد على مصدر بيانات النموذج لأي مَعلمات موصِّلات غير محدّدة. على سبيل المثال، يمكنك تغيير رقم تعريف مشروع الفوترة فقط لإعدادات مصدر بيانات 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

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

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

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

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

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

لتطبيق مَعلمة ربط 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

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

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

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

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

مرجع الموصل

تتيح واجهة برمجة تطبيقات الربط الموصلات والإعدادات التالية: لكل موصِّل، يتم توفير قائمة بمعلمات مصدر البيانات المتاحة.

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" أو 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 for Firebase. وبالنسبة إلى جداول Firebase Crashlytics، يتم ضبط القيمة التلقائية على DEFAULT في حال عدم تحديد ذلك.

طلبات بحث CUSTOM

تسري المعلمات التالية عند ضبط 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 في موصّل 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 في أداة ربط المنتدى. في حال ضبط هذه السياسة، سيتم استبدال مصدر البيانات بإعدادات "موصِّل المنتدى" المقدَّمة. راجِع الاستبدال مقابل التعديل.
ds.alias.connectorId	مطلوبة** أداة ربط المنتدى 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 للحصول على التفاصيل.

ملاحظة: إعدادات Universal Analytics (UA) و"إحصاءات Google 4" (GA4) غير متوافقة لأنّه تحتوي على مجموعات مختلفة من السمات والمقاييس. لن تنجح إعدادات ضبط Universal Analytics لمصدر بيانات تم إنشاؤه لموقع على "إحصاءات Google 4" والعكس صحيح. ننصحك بضبط المَعلمة ds.refreshFields على السمة true إذا كنت تريد أن يعمل نموذج التقرير مع أيٍّ من الموقعَين.

أمثلة

أحد إعدادات "إحصاءات 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 Explore.
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 للحصول على التفاصيل.

مثال

إعدادات Search Console لموقع إلكتروني يبدأ بعنوان URL:

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

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

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

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

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

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

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

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

نقطة رئيسية: يمكن ضبط معلَمات التحكّم، بخلاف reportId و Report، عند استخدام تقرير فارغ أو تلقائي.

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

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

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 المضمّن في واجهة برمجة التطبيقات للربط على النحو التالي:

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

البحث عن المعرّفات والأسماء المستعارة

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

للعثور على رقم تعريف التقرير:

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

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

ابحث عن رقم تعريف التقرير في عنوان URL للتقرير.

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

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

للعثور على اسم مستعار لمصدر بيانات:

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

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

ابحث عن العنوان البديل لمصدر البيانات في صفحة إدارة مصادر البيانات.

نوع الموصّل

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

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

ابحث عن نوع رابط مصدر البيانات في صفحة إدارة مصادر البيانات.

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

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

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

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

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

  

• في حال عدم توفّر زر معلومات، يمكنك تفعيل الزر من خلال إلحاق المَعلمة &c.explain=true بنهاية أي عنوان URL لربط واجهة برمجة التطبيقات.

الأذونات

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

التحديث مقابل الاستبدال

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

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

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

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

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

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

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

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

• في حال ضبط هذه السياسة على false، سيتم نقل إعدادات الحقل من مصدر بيانات النموذج إلى مصدر البيانات الجديد والرسوم البيانية للتقارير، وسيتم تحميل الحقول نفسها بنفس الإعدادات، وسيتم تحميلها بنجاح.

نقطة رئيسية: الحقول المحسوبة والمَعلمات المحدّدة في مصادر بيانات النموذج سيتم نقلها دائمًا إلى مصادر البيانات التي تم إنشاؤها حديثًا ولن تتأثر بقيمة refreshFields.

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

استخدِم أداة تتبُّع المشاكل للإبلاغ عن مشاكل ربط واجهة برمجة التطبيقات أو تقديم ملاحظات وآراء. راجِع الدعم للاطّلاع على مراجع عامة عن الحصول على المساعدة وطرح الأسئلة.

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

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.
  • انتهت الفترة التجريبية لربط واجهة برمجة التطبيقات.
• تمت إضافة مَعلمة التحكّم 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.
• موصِّل "استطلاعات Google"
  • تقبل surveyId الآن رقم تعريف استطلاع واحدًا أو قائمة من معرّفات الاستطلاع مفصولة بفواصل.

2021-12-16

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