پیوند API

مقدمه

رابط برنامه‌نویسی کاربردی لینکینگ (Linking API) یک رابط کاربری قابل اعتماد برای پیکربندی و هدایت مستقیم کاربران به گزارش Looker Studio از طریق یک URL فراهم می‌کند. هنگامی که کاربران URL رابط برنامه‌نویسی کاربردی لینکینگ را دنبال می‌کنند، یک تجربه ساده برای مشاهده سریع و تعامل با داده‌های خود خواهند داشت.

این سند قالب مورد نیاز URL های Linking API و پارامترهای موجود را شرح می‌دهد.

مورد استفاده و مزایا

از Linking API می‌توان برای ارائه گزارش‌های از پیش تنظیم‌شده به مشتریان شما جهت مشاهده و تعامل با داده‌هایشان استفاده کرد. مزایای کلیدی Linking API به شرح زیر است:

• تجربه ایجاد گزارش با یک کلیک برای مشتریان شما .
  • پیکربندی داده‌ها در URL ارائه شده است، بنابراین کاربران نیازی به پیکربندی گزارش برای داده‌های خود ندارند.
  • کاربران می‌توانند گزارش را با یک کلیک ذخیره کنند و هر زمان که بخواهند، دوباره به آن مراجعه کنند.
• گزارش‌ها را در مقیاس بزرگ ایجاد کنید . رابط برنامه‌نویسی کاربردی پیوند، زمان لازم برای کپی کردن یا ایجاد گزارش‌های جدید را کاهش می‌دهد.
• فعال کردن ادغام محصولات . رابط کاربری پایدار به شما امکان می‌دهد Looker Studio را در گردش کار محصول ادغام کنید.

چگونه کار می‌کند؟

در ادامه نحوه تعامل توسعه‌دهندگان و کاربران با Linking API شرح داده شده است.

پیوند دادن گردش کار توسعه‌دهنده API

توسعه‌دهنده، گزارش‌های قالب، منابع داده و قالب‌بندی یک URL رابط برنامه‌نویسی کاربردی (API) را آماده می‌کند. گردش کار معمول برای توسعه‌دهندگان به شرح زیر است:

1. تصمیم بگیرید که آیا از یک گزارش خالی، الگوی گزارش پیش‌فرض ارائه شده توسط Looker Studio استفاده کنید یا یک گزارش Looker Studio ایجاد کنید که به عنوان الگو عمل کند. این شامل پیکربندی منابع داده الگو نیز می‌شود.
2. یک URL رابط برنامه‌نویسی کاربردی (API) برای مورد استفاده خاص خود قالب‌بندی کنید. در صورت لزوم، الگوی گزارش و سایر پارامترها، از جمله نام گزارش، نام منبع داده و پیکربندی منبع داده را مشخص کنید.
3. از لینک API URL برای هدایت کاربران به گزارش استفاده کنید.

پیوند دادن تجربه کاربری API

کاربر یک URL رابط برنامه‌نویسی کاربردی (API) را دنبال می‌کند که اگر توسط توسعه‌دهنده به درستی پیکربندی شده باشد، او را به یک گزارش Looker Studio هدایت می‌کند که به او امکان مشاهده و تعامل با داده‌هایی را که به آنها دسترسی دارد، می‌دهد. یک تجربه کاربری معمول ممکن است به شرح زیر باشد:

1. در یک مرورگر، کاربر از سرویسی بازدید می‌کند که با Linking API یکپارچه شده است.
2. یک فراخوان برای اقدام، کاربر را دعوت می‌کند تا برای مشاهده داده‌های خود در Looker Studio، روی لینکی کلیک کند.
3. کاربر لینک را دنبال می‌کند و به گزارش Looker Studio هدایت می‌شود. گزارش بارگذاری می‌شود و کاربر می‌تواند داده‌های خود را مشاهده و با آنها تعامل داشته باشد.
4. کاربر روی «ویرایش و اشتراک‌گذاری» کلیک می‌کند. گزارش در حساب کاربری Looker Studio او ذخیره می‌شود.
5. کاربر اکنون دسترسی و کنترل کامل بر نسخه خود از گزارش دارد. او می‌تواند در هر زمانی آن را مشاهده، ویرایش و به اشتراک بگذارد.

الزامات

برای اطمینان از اینکه URL مربوط به Linking API طبق انتظار کار می‌کند، موارد زیر لازم است:

1. یک گزارش، به عنوان الگو. در صورت عدم ارائه، می‌توان از یک گزارش خالی یا گزارش پیش‌فرض، ارائه شده توسط Looker Studio، استفاده کرد.
2. کاربران یک URL رابط کاربری لینک‌دهنده (Linking API URL) باید حداقل دسترسی مشاهده به گزارش الگو را داشته باشند. بسته به نوع منابع داده مورد استفاده در گزارش و پیکربندی ارائه شده از طریق رابط کاربری لینک‌دهنده، کاربران ممکن است به دسترسی مشاهده به منابع داده نیز نیاز داشته باشند. برای جزئیات بیشتر به مجوزهای الگو مراجعه کنید.
3. نوع کانکتور هر منبع داده باید از پیکربندی از طریق Linking API پشتیبانی کند. برای مشاهده لیست کانکتورهای پشتیبانی شده، به مرجع کانکتور مراجعه کنید.
4. کاربران Linking API URL باید به داده‌های پیکربندی‌شده در Linking API URL دسترسی داشته باشند. اگر کاربر به داده‌های اصلی دسترسی نداشته باشد، هر یک از اجزای گزارش وابسته، خطا نشان خواهند داد.

توجه: رابط برنامه‌نویسی کاربردی پیوند، دسترسی به داده‌های موجود، تنظیمات اشتراک‌گذاری یا الگوی گزارش اصلی و پیکربندی منبع داده را تغییر نمی‌دهد.

پارامترهای آدرس اینترنتی

یک URL مربوط به API لینک دهنده باید به شکل زیر باشد:

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

انتظار می‌رود این 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-encode کنید. برای جزئیات بیشتر در مورد ساخت یک URL معتبر، به بخش URL Encoding مراجعه کنید.

پارامترهای خاصی از URL مورد نیاز هستند، در حالی که برخی دیگر اختیاری هستند. در زیر لیستی از پارامترهایی که برای تعریف URL یک Linking API استفاده می‌شوند، آمده است:

پارامترهای کنترل

پارامترهای کنترل، وضعیت گزارش را هنگام مشاهده از طریق URL لینک 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	اختیاری. شناسه‌های اندازه‌گیری گوگل آنالیتیکس را برای اندازه‌گیری میزان استفاده از گزارش تنظیم می‌کند. برای جدا کردن چندین شناسه از کاما استفاده کنید. اگر r.measurementId و r.keepMeasurementId مشخص نشده باشند، تنظیمات گزارش شناسه‌های اندازه‌گیری گوگل آنالیتیکس به صورت پیش‌فرض روی unset قرار می‌گیرد. اگر r.measurementId و r.keepMeasurementId تنظیم شده باشند، r.keepMeasurementId برای تنظیم شناسه اولویت دارد.
r.keepMeasurementId	اختیاری. برای استفاده از الگوی گزارش، شناسه‌های اندازه‌گیری گوگل آنالیتیکس را روی true تنظیم کنید. در صورت عدم تعیین، پیش‌فرض روی false است. اگر r.measurementId و r.keepMeasurementId مشخص نشده باشند، تنظیمات گزارش شناسه‌های اندازه‌گیری گوگل آنالیتیکس به صورت پیش‌فرض روی unset قرار می‌گیرد. اگر 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 لینکینگ API و منابع داده مرتبط توصیه می‌شود.

پارامترهای منبع داده

پارامترهای زیر در بین همه انواع کانکتورها مشترک هستند:

نام	توضیحات
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 API لینکینگ مشخص شوند و پیکربندی منبع داده قالب به طور کامل جایگزین خواهد شد. اگر مشخص نشده باشد، می‌توان صفر یا چند پارامتر کانکتور برای نوع کانکتور در URL مربوط به Linking API مشخص کرد. پیکربندی منبع داده قالب برای مشخص کردن هر پارامتری که در URL مربوط به Linking API ارائه نشده است، استفاده خواهد شد. برای جزئیات بیشتر در مورد نحوه شناسایی نوع کانکتور منبع داده قالب، به نوع کانکتور مراجعه کنید. برای کسب اطلاعات بیشتر در مورد چگونگی تأثیر پارامتر ds.connector بر اینکه آیا پیکربندی منبع داده قالب به طور کامل جایگزین می‌شود یا برای به‌روزرسانی پارامترهای نامشخص استفاده می‌شود، به بخش Replace در مقابل update مراجعه کنید.
ds. alias .refreshFields	اختیاری. برای استفاده از پیکربندی منبع داده مشخص شده از طریق Linking API، مقدار آن را روی true تنظیم کنید تا فیلدهای منبع داده را به‌روزرسانی کرده و اجزای گزارش را با انتخاب‌های فیلد جدید به‌روزرسانی کند. مقدار 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 لینکینگ API جایگزین می‌شود. شما باید تمام پارامترهای مورد نیاز برای نوع کانکتور را مشخص کنید. به پارامترهای مورد نیاز هنگام تنظیم ds.connector مراجعه کنید.	هنگام تغییر نوع رابط یک منبع داده. به عنوان مثال، اگر یک منبع داده BigQuery را در گزارش قالب پیکربندی کرده‌اید، اما می‌خواهید یک منبع داده Sheets را از طریق Linking API پیکربندی کنید. این امر مستلزم تعریف کامل پیکربندی رابط جدید است. وقتی می‌خواهید پیکربندی یک منبع داده را تضمین کنید. جایگزینی پیکربندی از هرگونه مقادیر ناشناخته‌ای که به طور بالقوه از منبع داده الگو استفاده می‌شوند، جلوگیری می‌کند.
خیر	به‌روزرسانی . پیکربندی منبع داده قالب برای مشخص کردن هر پارامتری که در URL رابط کاربری لینکینگ ارائه نشده است، استفاده خواهد شد. تمام پارامترهای کانکتور برای نوع کانکتور اختیاری هستند، مگر اینکه خلاف آن ذکر شده باشد. این کار آدرس URL مربوط به 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

وقتی گزارش فقط یک منبع داده دارد، می‌توان نام مستعار منبع داده را حذف کرد. آدرس اینترنتی بالا را می‌توان به شکل زیر ساده کرد:

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 Analytics ( ds1 ) پیکربندی می‌کند. پیکربندی منبع داده BigQuery به طور کامل جایگزین می‌شود، در حالی که پیکربندی Google Analytics یک پارامتر واحد را به‌روزرسانی می‌کند و برای هر پارامتر کانکتور نامشخص، به منبع داده الگوی 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، می‌توانید با اطمینان از برآورده شدن تمام شرایط زیر، یک منبع داده را از گزارش الگوی خود دوباره اضافه کنید:

1. منبع داده قابل استفاده مجدد است (به مقایسه منابع داده جاسازی شده و قابل استفاده مجدد مراجعه کنید)
2. آدرس اینترنتی (url) با نام مستعار به منبع داده اشاره نمی‌کند.
3. این آدرس اینترنتی از نام مستعار wildcard استفاده نمی‌کند (به بخش نام مستعار منبع داده wildcard مراجعه کنید)

وقتی یک منبع داده جدید با استفاده از Linking API ایجاد می‌شود، از اعتبارنامه‌های کاربری که روی آدرس اینترنتی کلیک کرده است استفاده می‌کند. این بدان معناست که کاربر باید به داده‌های اصلی دسترسی داشته باشد، در غیر این صورت اتصال برقرار نخواهد شد. با اضافه کردن مجدد منبع داده به گزارش تازه تولید شده، می‌توانید اعتبارنامه‌های آن را حفظ کنید تا کاربران بتوانند در گزارش‌های جدید خود به داده‌ها دسترسی داشته باشند.

نام مستعار منبع داده (wildcard)

برای اعمال یک پارامتر Linking API به چندین منبع داده، می‌توان از نام مستعار wildcard ds.* به جای نام مستعار منبع داده استفاده کرد.

این می‌تواند برای حذف پارامترهای تکراری از آدرس اینترنتی شما مفید باشد. برای مثال، اگر الگویی با سه منبع داده 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.* ، می‌توانید از این آدرس اینترنتی معادل استفاده کنید:

  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

به طور کلی، ترتیب اولویت پارامترها به صورت زیر است:

1. پارامتری که با نام مستعار خاص ( ds.ds1.datasetId ) داده می‌شود.
2. پارامتری که با استفاده از کاراکترهای عمومی ( ds.*.datasetId ) ارائه می‌شود
3. مقداری که از منبع داده‌ی الگو گرفته شده است، اگر ds.connector ارائه نشده باشد (به بخش Replace در مقابل update مراجعه کنید)
4. مقدار پیش‌فرض برای پارامتر، در صورتی که اختیاری باشد.

مرجع کانکتور

رابط برنامه‌نویسی کاربردی پیوند (Linking API) از کانکتورها و پیکربندی‌های زیر پشتیبانی می‌کند. برای هر کانکتور، فهرست پارامترهای منبع داده‌ی موجود ارائه شده است.

بیگ‌کوئری

رابط BigQuery از دو نوع پرس‌وجو پشتیبانی می‌کند، یک پرس‌وجوی TABLE که در آن شناسه جدول مورد نظر برای پرس‌وجو را ارائه می‌دهید و یک CUSTOM_QUERY که در آن یک دستور SQL برای پرس‌وجو از یک جدول ارائه می‌دهید.

پرس‌وجوهای جدول

پارامترهای زیر زمانی قابل اجرا هستند که type روی TABLE تنظیم شده باشد و شما شناسه جدول را برای پرس و جو ارائه دهید.

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای کانکتور BigQuery روی bigQuery تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی BigQuery ارائه شده جایگزین می‌کند. به Replace در مقابل update مراجعه کنید.
ds. alias .type	الزامی ** نوع پرس‌وجو. روی TABLE تنظیم شود.
ds. alias .projectId	الزامی ** شناسه پروژه جدول مورد نظر برای پرس و جو.
ds. alias .datasetId	الزامی ** شناسه مجموعه داده جدول مورد نظر برای پرس و جو.
ds. alias .tableId	الزامی ** شناسه جدول مورد نظر برای پرس و جو. جداول خرد شده تاریخ : هنگام پرس‌وجو از جداول خرد شده‌ی تاریخ، از * (کاراکتر wildcard) یا پسوند YYYYMMDD پشتیبانی می‌شود. اگر جدولی به عنوان Google Analytics، Firebase Analytics یا Firebase Crashlytics شناسایی شود، یک الگوی فیلد پیش‌فرض انتخاب خواهد شد، مگر اینکه الگویی مشخص شده باشد. به پارامترهای مربوط به جدول الگوی فیلدها مراجعه کنید.
ds. alias .billingProjectId	اختیاری. شناسه پروژه برای استفاده در صدور صورتحساب. در صورت عدم تنظیم، projectId استفاده خواهد شد.
ds. alias .isPartitioned پارتیشن‌بندی شده	اختیاری. اگر جدول پارتیشن‌بندی شده باشد و بخواهید از ستون پارتیشن‌بندی به عنوان بُعد محدوده تاریخ استفاده کنید، روی true تنظیم کنید. این فقط برای پارتیشن‌بندی مبتنی بر زمان (مثلاً با استفاده از ستون پارتیشن‌بندی مبتنی بر زمان یا شبه ستون _PARTITIONTIME ) قابل اجرا است و برای جداول پارتیشن‌بندی شده با محدوده عدد صحیح کار نمی‌کند. در صورت عدم تعیین مقدار، پیش‌فرض روی false است. برای کسب اطلاعات بیشتر به مقدمه‌ای بر جداول پارتیشن‌بندی شده مراجعه کنید.
ds. alias .refreshFields	اختیاری. در صورت عدم تعیین مقدار، پیش‌فرض true است. برای جزئیات بیشتر به refreshFields مراجعه کنید.

قالب فیلدها برای گوگل آنالیتیکس، فایربیس آنالیتیکس و کراش‌لیتیکز

برای جداولی که به عنوان Google Analytics، Firebase Analytics یا Firebase Crashlytics شناسایی می‌شوند، پارامترهای اضافی برای تنظیم الگوی فیلدها در دسترس هستند. در صورت عدم تعیین، یک الگوی پیش‌فرض انتخاب خواهد شد.

نام	توضیحات
ds. alias .gaTemplateLevel	اختیاری. الگوی فیلدهای گوگل آنالیتیکس مورد استفاده. فقط زمانی اعمال می‌شود که یک خروجی BigQuery برای جدول گوگل آنالیتیکس در حال پرس‌وجو باشد. یکی از موارد ALL ، SESSION ، HITS . برای جداول گوگل آنالیتیکس، در صورت عدم تعیین، پیش‌فرض ALL است.
ds. alias .firebaseTemplateLevel	اختیاری. الگوی فیلدهای Firebase Analytics برای استفاده. فقط زمانی اعمال می‌شود که یک خروجی BigQuery برای جدول Firebase Analytics در حال پرس‌وجو باشد. فقط می‌توان آن را روی EVENTS تنظیم کرد. برای جداول Firebase Analytics، در صورت عدم تعیین، پیش‌فرض روی EVENTS است.
ds. alias .crashlyticsTemplateLevel	الگوی فیلدهای Firebase Crashlytics برای استفاده. فقط می‌توان آن را روی DEFAULT تنظیم کرد. فقط زمانی اعمال می‌شود که یک خروجی BigQuery برای جدول Firebase Crashlytics در حال پرس‌وجو باشد. برای جداول Firebase Crashlytics، اگر مشخص نشود، پیش‌فرض روی DEFAULT است.

پرس‌وجوهای سفارشی

پارامترهای زیر زمانی قابل اجرا هستند که type روی CUSTOM_QUERY تنظیم شده باشد و شما یک دستور SQL برای پرس و جو از یک جدول ارائه دهید.

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای کانکتور BigQuery روی bigQuery تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی BigQuery ارائه شده جایگزین می‌کند. به Replace در مقابل update مراجعه کنید.
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 که در آن پرس‌وجو با شناسه جدول (Table ID) تعریف می‌شود:

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 برای پرس‌وجو از یک جدول خرد شده تاریخ با استفاده از پسوند کاراکتر wildcard:

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 Analytics، با استفاده از الگوی فیلدهای 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

آچار ابری

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای کانکتور Cloud Spanner، مقدار را روی cloudSpanner تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی Cloud Spanner ارائه شده جایگزین می‌کند. به Replace در مقابل update مراجعه کنید.
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 جایگزین می‌کند. به بخش Replace در مقابل update مراجعه کنید.
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

نکته: برای کانکتورهایی که از پیکربندی پله‌ای استفاده می‌کنند، نیازی به مراقبت ویژه نیست .

گوگل آنالیتیکس

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای رابط گوگل آنالیتیکس، روی googleAnalytics تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی ارائه شده Google Analytics جایگزین می‌کند. به بخش «جایگزینی در مقابل به‌روزرسانی» مراجعه کنید.
ds. alias .accountId	الزامی ** شناسه حساب کاربری.
ds. alias .propertyId	الزامی ** شناسه ملک.
ds. alias .viewId	شناسه نمایش. برای ویژگی‌های Universal Analytics الزامی است. ** برای ویژگی‌های Google Analytics 4 تنظیم نکنید.
ds. alias .refreshFields	اختیاری. در صورت عدم تعیین مقدار، پیش‌فرض false است. برای جزئیات بیشتر به refreshFields مراجعه کنید.

توجه: پیکربندی‌های Universal Analytics (UA) و Google Analytics 4 (GA4) با هم سازگار نیستند زیرا مجموعه ابعاد و معیارهای متفاوتی دارند. تنظیم پیکربندی UA برای منبع داده‌ای که برای یک ویژگی GA4 ایجاد شده است، کار نخواهد کرد و برعکس. اگر می‌خواهید الگوی گزارش شما با هر یک از این ویژگی‌ها کار کند، تنظیم پارامتر ds.refreshFields را روی true در نظر بگیرید.

مثال‌ها

پیکربندی گوگل آنالیتیکس برای یک ویژگی 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

پیکربندی گوگل آنالیتیکس برای یک ویژگی گوگل آنالیتیکس ۴:

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

فضای ذخیره‌سازی ابری گوگل

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. روی googleCloudStorage تنظیم کنید. رابط ذخیره‌سازی ابری گوگل . در صورت تنظیم، منبع داده را با پیکربندی ارائه شده‌ی فضای ذخیره‌سازی ابری گوگل جایگزین می‌کند. به «جایگزینی در مقابل به‌روزرسانی» مراجعه کنید.
ds. alias .pathType	الزامی ** نوع مسیر. FILE برای انتخاب یک فایل و از FOLDER برای انتخاب همه فایل‌ها در مسیر داده شده استفاده کنید.
ds. alias .path مسیر	الزامی ** مسیر فایل (مثلاً MyBucket/MyData/MyFile.csv ) اگر pathType FILE باشد یا مسیر پوشه (مثلاً *MyBucket/MyData ) اگر pathType FOLDER باشد.
ds. alias .refreshFields	اختیاری. در صورت عدم تعیین مقدار، پیش‌فرض true است. برای جزئیات بیشتر به refreshFields مراجعه کنید.

مثال

پیکربندی فضای ذخیره‌سازی ابری گوگل برای یک فایل:

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

پیکربندی فضای ذخیره‌سازی ابری گوگل برای همه فایل‌های موجود در مسیر:

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

صفحات گوگل

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای رابط Google Sheets، googleSheets را تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی Google Sheets ارائه شده جایگزین می‌کند. به بخش Replace در مقابل update مراجعه کنید.
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 مراجعه کنید.

مثال‌ها

پیکربندی گوگل شیت:

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

پیکربندی Google Sheets با ردیف اول به عنوان سرصفحه و سلول‌های پنهان و فیلتر شده شامل موارد زیر است:

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 Sheets با محدوده (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

تماشاچی

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای کانکتور Looker، مقدار looker را تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی Looker ارائه شده جایگزین می‌کند. به Replace در مقابل update مراجعه کنید.
ds. alias .instanceUrl	الزامی ** آدرس اینترنتی نمونه Looker.
ds. alias .model مدل	الزامی ** مدل Looker.
ds. alias .explore	الزامی ** جستجوگر کاوش.
ds. alias .refreshFields	اختیاری. در صورت عدم تعیین مقدار، پیش‌فرض false است. برای جزئیات بیشتر به refreshFields مراجعه کنید.

مثال

به یک جستجوگر متصل شوید:

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

کنسول جستجو

نام پارامتر	توضیحات
ds. alias .connector	اختیاری. برای رابط کنسول جستجو searchConsole را تنظیم کنید. در صورت تنظیم، منبع داده را با پیکربندی ارائه شده در کنسول جستجو جایگزین می‌کند. به بخش جایگزینی در مقابل به‌روزرسانی مراجعه کنید.
ds. alias .siteUrl	الزامی ** آدرس سایت. برای یک ویژگی دامنه ، پیشوندی با sc-domain\: .
ds. alias .tableType	الزامی ** نوع جدول را تنظیم می‌کند. می‌تواند یکی از SITE_IMPRESSION یا URL_IMPRESSION باشد.
ds. alias .searchType نوع جستجو	الزامی ** نوع جستجو را تنظیم می‌کند. می‌تواند یکی از WEB ، IMAGE ، VIDEO یا NEWS باشد.
ds. alias .refreshFields	اختیاری. در صورت عدم تعیین مقدار، پیش‌فرض false است. برای جزئیات بیشتر به refreshFields مراجعه کنید.

مثال

پیکربندی کنسول جستجو برای ویژگی پیشوند 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

پیکربندی کنسول جستجو برای یک ویژگی دامنه :

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 ارائه می‌دهد:

نوع منبع داده	پیکربندی API برای منبع داده را لینک کنید	توصیه‌هایی برای مجوزهای منبع داده	یادداشت‌ها
جاسازی شده	جایگزین کردن	ناموجود - دسترسی به نما از گزارش به ارث برده خواهد شد.	اگر کاربر به گزارش الگو دسترسی مشاهده داشته باشد، به طور خودکار به هر منبع داده تعبیه شده نیز دسترسی مشاهده خواهد داشت.
جاسازی شده	به‌روزرسانی	ناموجود - دسترسی به نما از گزارش به ارث برده خواهد شد.	اگر کاربر به گزارش الگو دسترسی مشاهده داشته باشد، به طور خودکار به هر منبع داده تعبیه شده نیز دسترسی مشاهده خواهد داشت.
قابل استفاده مجدد	جایگزین کردن	کاربران نیازی به دسترسی مشاهده ندارند.	از آنجایی که پیکربندی منبع داده به طور کامل از طریق Linking API جایگزین می‌شود، دسترسی به نما (view) لازم نیست.
قابل استفاده مجدد	به‌روزرسانی	کاربر به دسترسی مشاهده نیاز دارد.	دسترسی View به منبع داده برای اینکه Linking API بتواند پیکربندی را از منبع داده قالب بخواند و استفاده کند، ضروری است. اگر کاربران دسترسی View نداشته باشند، هنگام بارگیری گزارش خطایی دریافت خواهند کرد.

استفاده از گزارش خالی یا پیش‌فرض

برای استفاده از یک گزارش خالی یا گزارش پیش‌فرض، Linking API خود را به صورت زیر پیکربندی کنید:

نوع گزارش	پارامتر کنترل reportId را تنظیم کنید	پارامترهای منبع داده ( ds ) را تنظیم کنید.	یادداشت‌ها
گزارش خالی	خیر	خیر
گزارش پیش‌فرض	خیر	بله	گزارش پیش‌فرض توسط Looker Studio ارائه می‌شود. هنگام تعیین پارامترهای منبع داده برای گزارش پیش‌فرض، نیازی به استفاده از نام مستعار منبع داده نیست، زیرا گزارش پیش‌فرض دارای یک منبع داده‌ی واحد است.

نکته کلیدی: پارامترهای کنترل ، به غیر از reportId ، و پارامترهای گزارش را می‌توان هنگام استفاده از گزارش خالی یا پیش‌فرض تنظیم کرد.

مثال‌های زیر URLهای مختلف Linking API را نشان می‌دهند که از گزارش خالی یا پیش‌فرض استفاده می‌کنند.

گردش کار ایجاد گزارش را با یک گزارش خالی آغاز کنید:

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

گردش کار ایجاد گزارش را با یک گزارش خالی آغاز کنید و نام گزارش را تنظیم کنید:

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

از الگوی گزارش پیش‌فرض با پیکربندی رابط Google Sheets استفاده کنید:

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

پیدا کردن شناسه‌ها و نام‌های مستعار

شناسه گزارش

برای یافتن شناسه گزارش:

1. گزارشی را که می‌خواهید به عنوان الگو استفاده کنید، باز کنید. آدرس اینترنتی (URL) گزارش را بررسی کنید. قسمت بین reporting/ و /page شناسه گزارش است. برای مثال، در آدرس اینترنتی زیر، 0B_U5RNpwhcE6SF85TENURnc4UjA شناسه گزارش است:

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

شناسه گزارش را در آدرس اینترنتی گزارش پیدا کنید.

نام مستعار منبع داده

یک گزارش می‌تواند چندین منبع داده داشته باشد. یک منبع داده باید با نام مستعار آن ارجاع داده شود.

برای یافتن نام مستعار منبع داده:

1. گزارش را ویرایش کنید.
2. از نوار ابزار، گزینه Resource > Manage added data sources را انتخاب کنید.
3. ستون «نام مستعار» (Alias) را بررسی کنید تا اطلاعات نام مستعار را برای هر منبع داده پیدا کنید.

شما می‌توانید نام‌های مستعار را ویرایش کنید تا هنگام اضافه یا حذف یک منبع داده، سازگاری با نسخه‌های قبلی تضمین شود.

نام مستعار منبع داده را در صفحه مدیریت منابع داده پیدا کنید.

نوع کانکتور

یک گزارش می‌تواند چندین منبع داده داشته باشد که هر کدام با پیکربندی یک کانکتور ایجاد می‌شوند. برای یافتن نوع کانکتور مورد استفاده برای ایجاد یک منبع داده:

1. گزارش را ویرایش کنید.
2. از نوار ابزار، گزینه Resource > Manage added data sources را انتخاب کنید.
3. ستون نوع رابط (Connector Type) را بررسی کنید تا رابط مورد استفاده برای ایجاد منبع داده را شناسایی کنید.

نوع رابط منبع داده را در صفحه مدیریت منابع داده پیدا کنید.

نکات و عیب‌یابی

اگر با مشکل مواجه شدید، جزئیات زیر را بررسی کنید تا مشکلات احتمالی و پیکربندی‌های نادرست رایج را شناسایی کنید.

گفتگوی اشکال‌زدایی

از کادر محاوره‌ای اشکال‌زدایی برای بررسی پیکربندی Linking API همانطور که توسط Looker Studio تفسیر شده است، استفاده کنید. این می‌تواند به اشکال‌زدایی مشکلات مربوط به API کمک کند.

• وقتی در هنگام تجزیه URL مربوط به Linking API خطایی رخ دهد، به طور خودکار پنجره‌ای حاوی جزئیات خطا نمایش داده می‌شود.
• وقتی خطایی رخ می‌دهد و هیچ پنجره‌ای به طور خودکار نمایش داده نمی‌شود، به دنبال دکمه اطلاعات در سمت راست بالای گزارش باشید. برای اطلاعات بیشتر در مورد اشکال‌زدایی، روی آن کلیک کنید.

  

• اگر دکمه اطلاعات در دسترس نیست، می‌توانید با افزودن پارامتر &c.explain=true به انتهای هر URL مربوط به Linking API، دکمه را فعال کنید.

مجوزها

مطمئن شوید که مجوزهای قالب صحیح را برای انواع منبع داده و پیکربندی API پیوند تنظیم کرده‌اید. برای جزئیات بیشتر به مجوزهای قالب مراجعه کنید.

به‌روزرسانی در مقابل جایگزینی

اگر پیکربندی منبع داده را از یک الگوی منبع داده به‌روزرسانی می‌کنید، پیکربندی منبع داده الگو و پیکربندی Linking API را بررسی کنید تا از سازگاری آنها اطمینان حاصل شود. تأیید کنید که فیلدهای حاصل از پیکربندی جدید با اجزای گزارش و پیکربندی سازگار هستند.

هنگام انجام به‌روزرسانی در مقابل جایگزینی، می‌توان پیکربندی نامعتبری با رفتار نامشخص تنظیم کرد. برای جزئیات بیشتر به بخش جایگزینی در مقابل به‌روزرسانی مراجعه کنید.

فیلدها را تازه کنید

اگر نام، نوع یا تجمیع فیلدها را برای یک منبع داده‌ی الگو پیکربندی کرده‌اید، این تغییرات فقط در صورتی به یک منبع داده‌ی پیکربندی‌شده با Linking API منتقل می‌شوند که پارامتر ds.refreshFields روی false تنظیم شده باشد.

Review the ds.refreshFields data source parameter of your Linking API URL. If omitted, confirm that the default value of the parameter for each connector type is correct for your use case.

Generally, if you have configured fields in the template data source and are certain that new data source configurations via the Linking API will always yield the exact same fields, then setting refreshFields to false is recommended.

For example, if during the creation of a report template, Looker Studio identifies a particular data source field as type Number and you change it to type Year , this field configuration change is now part of the template data source. Any chart in the report template that uses the corrected field will expect a Year and if the chart is time-based it may not render otherwise. If the Linking API is used to provide a new data source configuration that yields the exact same fields, there are two outcomes based on the value of the refreshFields parameter:

• If set to true , the field configuration from the template data source will not carry-over, and charts may potentially fail to load if they depend on the same field configuration (ie a field of type Year is expected).

• If set to false , the field configuration from the template data source will carry-over to the new data source and report charts will receive the same fields with the same configuration and load successfully.

Key Point: Calculated fields and Parameters defined in template data sources will always carry-over to newly created data sources and are not affected by the value of refreshFields .

بازخورد و پشتیبانی

Use the Issue Tracker to report Linking API issues or to provide feedback. See Support for general resources on getting help and asking questions.

تغییرات

2023-06-06

• Added r.measurementId and r.keepMeasurementId report parameters to configure the Google Analytics Measurement IDs report setting.
• Added ds.keepDatasourceName to control reuse of the template data source name.
• Added an Embed report section.
• BigQuery connector
  • Added sqlReplace . Lets you specify pattern and replacement strings to update the SQL query of the template data source.

۲۰۲۳-۰۵-۲۲

• Added support for the Looker connector.
• Added support for Community Connectors .

2022-11-21

• Added the capability to use a blank report. See Use a blank or default report
• Added a refreshFields section to Tips & troubleshooting .

2022-11-14

• The Surveys connector reference has been removed due to the Google Surveys Sunset .

2022-06-15

• Out of beta
  • The Integration API has been renamed to Linking API .
  • Linking API is out of beta.
• Added the pageId control parameter to allow linking to a specific report page.
• Added the mode control parameter to set the report state to View or Edit mode on load.
• Data sources configurations can now be replaced entirely or partially updated. This behavior is determined by whether the ds.connector parameter is set. See Replace vs update for details.
• A default template is now used if a report template is not provide using the c.reportId parameter.
• Added the ds.refreshFields data source parameter. This allows you to control whether data source fields are refreshed when loading a data source configuration.
• BigQuery connector
  • projectId is not required when type is set to CUSTOM_QUERY .
  • When billingProjectId is not set then the billing project will fallback to projectId or the project of the queried table.
  • Added support for date partitioned tables. Set the isPartitioned parameter to true to use the partition field as a date range dimension.
  • Added support for querying date partitioned tables using the wildcard character or YYYYMMDD table suffix.
  • Added support for querying Google Analytics, Firebase Analytics, or Crashlytics tables and selecting a fields template.
• Google Sheets
  • hasHeader defaults to true , consistent with the web UI default.
  • includeHiddenAndFilteredCell split into includeHiddenCells and
  • includeFilteredCells . Both now default to true , consistent with the web UI default.
• Search Console connector
  • Renamed the propertyType parameter to searchType .
• Surveys connector
  • surveyId now accepts a single survey ID or a comma-separated list of survey IDs.

۲۰۲۱-۱۲-۱۶

• Initial release of the Integration API.
  • Supports linking to an existing report and setting the report name.
  • Multiple data sources can be configured and each data source name can be set.
  • Support for the following connector types: BigQuery, Cloud Spanner, Google Analytics, Google Cloud Storage, Google Sheets, Google Surveys, Search Console.