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

مقدمة

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

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

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

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

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

آلية العمل

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

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

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

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

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

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

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

المتطلبات

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

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

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`، سيتم تلقائيًا استخدام اصطلاح تسمية يتضمّن نوع أداة الربط ووقت الإنشاء (مثلاً، عينات - 12/12/21، الساعة 10:53 مساءً) كاسم لمصدر البيانات. في حال ضبط `ds.datasourceName` و`ds.keepDatasourceName`، تكون الأولوية لـ `ds.datasourceName` في تحديد اسم مصدر البيانات.
`ds.alias.keepDatasourceName`	اختياريّ. اضبط القيمة على `true` لاستخدام اسم مصدر بيانات النموذج. يتم ضبط القيمة تلقائيًا على `false` في حال عدم تحديدها. في حال عدم تحديد `ds.datasourceName` و`ds.keepDatasourceName`، سيتم تلقائيًا استخدام اصطلاح تسمية يتضمّن نوع أداة الربط ووقت الإنشاء (مثلاً، عينات - 12/12/21، الساعة 10:53 مساءً) كاسم لمصدر البيانات. في حال ضبط `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 للبحث في جدول.

طلبات البحث في الجداول

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

أمثلة

إعدادات "إحصاءات 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.

مثال

إعدادات موقع إلكتروني على 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

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

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

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

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

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

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

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

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

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

لا

نعم

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

يتم توفير التقرير التلقائي من خلال Looker Studio.

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

تعرض الأمثلة التالية عناوين 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 لتقرير Looker Studio.
تم تمييز رقم تعريف التقرير. — ابحث عن معرّف البلاغ في عنوان URL الخاص بالتقرير.

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

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

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

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

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

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

نوع الموصّل

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

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

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

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

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

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

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

عند حدوث خطأ أثناء تحليل عنوان 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.

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

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

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

استخدِم أداة تتبُّع المشاكل للإبلاغ عن مشاكل في 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

طلبات البحث في الجداول

نموذج الحقول في "إحصاءات 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`