معرفی
Linking API یک رابط قابل اعتماد برای پیکربندی و ارسال مستقیم کاربران به گزارش Looker Studio از طریق URL فراهم می کند. وقتی کاربران یک URL API پیوندی را دنبال میکنند، تجربه کارآمدی برای مشاهده سریع و تعامل با دادههای خود خواهند داشت.
این سند فرمت مورد نیاز پیوند URL های API و پارامترهای موجود را شرح می دهد.
مورد استفاده و مزایا
Linking API می تواند برای ارائه گزارش های از پیش پیکربندی شده برای مشتریان شما برای مشاهده و تعامل با داده های آنها استفاده شود. مزایای کلیدی Linking API به شرح زیر است:
- تجربه ایجاد گزارش با یک کلیک برای مشتریان شما .
- پیکربندی داده در URL ارائه شده است، بنابراین کاربران نیازی به پیکربندی گزارش برای داده های خود ندارند.
- کاربران می توانند گزارش را با یک کلیک ذخیره کنند و در هر زمان که بخواهند دوباره از گزارش بازدید کنند.
- ایجاد گزارش در مقیاس Linking API زمان مورد نیاز برای کپی کردن یا ایجاد گزارشهای جدید را کاهش میدهد.
- ادغام محصول را فعال کنید رابط پایدار به شما امکان می دهد Looker Studio را در یک گردش کاری محصول ادغام کنید.
چگونه کار می کند
در ادامه نحوه تعامل توسعه دهندگان و کاربران با Linking API توضیح داده شده است.
پیوند دادن گردش کار توسعه دهنده API
توسعهدهنده گزارشهای الگو، منابع داده را آماده میکند و URL API پیوندی را قالببندی میکند. گردش کار معمول برای توسعه دهندگان به شرح زیر است:
- تصمیم بگیرید که آیا از یک گزارش خالی، الگوی گزارش پیشفرض ارائه شده توسط استودیو Looker استفاده کنید یا یک گزارش استودیو Looker ایجاد کنید که به عنوان یک الگو عمل کند. این شامل پیکربندی منابع داده الگو می شود.
- یک URL API پیوند را برای مورد خاص خود قالب بندی کنید. در صورت وجود، الگوی گزارش و سایر پارامترها، از جمله نام گزارش، نام منبع داده و پیکربندی منبع داده را مشخص کنید.
- برای هدایت کاربران به گزارش، از پیوند URL API استفاده کنید.
پیوند دادن تجربه کاربر API
کاربر یک URL API پیوندی را دنبال میکند، که اگر توسعهدهنده آن را به درستی پیکربندی کند، او را به گزارش Looker Studio هدایت میکند که به او اجازه میدهد دادههایی را که به آنها دسترسی دارد مشاهده کرده و با آنها تعامل داشته باشد. یک تجربه کاربری معمولی ممکن است به شرح زیر باشد:
- در یک مرورگر، کاربر از سرویسی بازدید می کند که با Linking API یکپارچه شده است.
- یک فراخوان برای اقدام از کاربر دعوت می کند تا برای مشاهده داده های خود در استودیو Looker روی پیوندی کلیک کند.
- کاربر پیوند را دنبال می کند و به گزارش Looker Studio هدایت می شود. گزارش بارگیری می شود و کاربر قادر به مشاهده و تعامل با داده های خود است.
- کاربر روی "ویرایش و اشتراک گذاری" کلیک می کند. گزارش در حساب Looker Studio آنها ذخیره می شود.
- کاربر اکنون دسترسی و کنترل کاملی بر نسخه خود از گزارش دارد. آنها می توانند در هر زمان مشاهده، ویرایش و اشتراک گذاری کنند.
الزامات
برای اطمینان از عملکرد لینک API URL همانطور که انتظار می رود، موارد زیر مورد نیاز است:
- یک گزارش، به عنوان یک الگو. اگر ارائه نشد، می توان از یک گزارش خالی یا گزارش پیش فرض ارائه شده توسط Looker Studio استفاده کرد.
- کاربران URL API پیوند دهنده باید حداقل دسترسی به گزارش الگو را داشته باشند. بسته به نوع منابع داده مورد استفاده در گزارش و پیکربندی ارائه شده از طریق Linking API، کاربران همچنین ممکن است نیاز به دسترسی به منابع داده داشته باشند. برای جزئیات بیشتر به مجوزهای الگو مراجعه کنید.
- نوع رابط هر منبع داده باید از پیکربندی از طریق Linking API پشتیبانی کند. برای لیستی از کانکتورهای پشتیبانی شده به مرجع Connector مراجعه کنید.
- کاربران لینک API URL باید به داده های پیکربندی شده در URL API پیوند دسترسی داشته باشند. اگر کاربر به داده های اساسی دسترسی نداشته باشد، هر مؤلفه گزارش وابسته یک خطا نشان می دهد.
پارامترهای URL
یک URL API پیوند دهنده باید به شکل زیر باشد:
https://lookerstudio.google.com/reporting/create?parameters
انتظار می رود که URL در زمینه یک مرورگر وب استفاده شود، معمولاً توسط کاربری که روی پیوند کلیک می کند یا به URL هدایت می شود. همچنین می توان از آن برای جاسازی گزارش استفاده کرد.
URL مثال
در زیر نمونه ای از پیوند URL 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 API پیوند داده شده است:
پارامترهای کنترل
پارامترهای کنترل وضعیت گزارش را هنگام مشاهده از طریق URL API Linking تعیین می کند.
نام پارامتر | شرح |
---|---|
اختیاری. شناسه گزارش الگو. Looker Studio گزارش مشخص شده را باز کرده و پیکربندی می کند. برای جزئیات بیشتر در مورد نحوه یافتن شناسه، به ID گزارش مراجعه کنید. اگر مشخص نیست، از یک گزارش خالی یا الگوی گزارش پیشفرض استفاده میشود، برای جزئیات بیشتر به استفاده از گزارش خالی یا پیشفرض مراجعه کنید. | |
اختیاری. شناسه صفحه اولیه برای بارگیری در گزارش. در صورت نامشخص بودن به صفحه اول گزارش به طور پیش فرض، . | |
اختیاری. حالت گزارش اولیه یکی از view یا edit . پیش فرض برای view در صورت نامشخص. | |
اختیاری. قابلیت مشاهده گفتگوی اطلاعات/اشکالزدایی. برای نمایش دکمه گفتگو روی 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
گزارش پارامترها
پارامترهای گزارش ویژگی های گزارش را نادیده می گیرند.
نام پارامتر | شرح |
---|---|
اختیاری. نام گزارش را تنظیم می کند. اگر نامشخص باشد، به طور پیشفرض روی نام گزارش الگو قرار میگیرد. | |
اختیاری. شناسههای اندازهگیری Google Analytics را روی اندازهگیری میزان مصرف گزارش تنظیم میکند. برای جدا کردن چند شناسه از کاما استفاده کنید. اگر | |
اختیاری. برای استفاده از گزارش الگو ، شناسههای اندازهگیری Google Analytics را روی اگر |
مثال
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 پیوند مشخص شود و پیکربندی منبع داده الگو به طور کامل جایگزین خواهد شد. اگر مشخص نشده باشد، صفر یا چند پارامتر رابط برای نوع رابط را می توان در URL API پیوندی مشخص کرد. پیکربندی منبع داده الگو برای تعیین هر پارامتری که در URL API پیوند داده نشده است، استفاده خواهد شد. برای جزئیات در مورد نحوه شناسایی نوع رابط منبع داده الگو، نوع رابط را ببینید. برای اطلاعات بیشتر در مورد اینکه چگونه پارامتر | |
اختیاری. برای استفاده از پیکربندی منبع داده مشخص شده از طریق Linking API برای بازخوانی فیلدهای منبع داده و به روز رسانی اجزای گزارش با انتخاب فیلدهای جدید، روی برای اینکه فیلدهای منبع داده نسبت به گزارش الگو تغییری نکنند، روی اگر مشخص نشده باشد، پیشفرضها براساس نوع رابط متفاوت است. در صورتی که میخواهید رفتار پیشفرض را لغو کنید، مرجع Connector را برای پیشفرضهای خاص رابط بررسی کنید. ملاحظات هنگام استفاده از refreshFields :
| |
مورد نیاز . پیکربندی منبع داده برای نوع رابط . برای جزئیات در مورد نحوه شناسایی رابط مورد استفاده برای ایجاد منبع داده، نوع رابط را ببینید. برای جزئیات در مورد پارامترهای منبع داده موجود برای هر نوع رابط، به مرجع اتصال مراجعه کنید. |
جایگزینی در مقابل بهروزرسانی - پیکربندیهای منبع داده
هنگام تنظیم پارامترهای منبع داده، وجود یا حذف پارامتر ds.connector
در URL API پیوند دادن به ترتیب نشان دهنده قصد جایگزینی یا به روز رسانی پیکربندی منبع داده الگو است.
جدول زیر نحوه تأثیر پارامتر ds.connector
را نشان می دهد که آیا پیکربندی منبع داده الگو به طور کامل جایگزین می شود یا برای به روز رسانی پارامترهای نامشخص استفاده می شود:
آیا ds.connector تنظیم شده است؟ | پیکربندی و رفتار مورد انتظار | استفاده معمولی |
---|---|---|
آره | جایگزین کنید . پیکربندی منبع داده الگو به طور کامل با استفاده از پارامترهای منبع داده مشخص شده در URL API پیوند داده شده است. شما باید تمام پارامترهای مورد نیاز برای نوع کانکتور را مشخص کنید. هنگام تنظیم ds.connector به پارامترهای مورد نیاز مراجعه کنید. |
|
خیر | به روز رسانی . پیکربندی منبع داده الگو برای تعیین هر پارامتری که در URL API پیوند داده نشده است، استفاده خواهد شد. تمام پارامترهای رابط برای نوع کانکتور اختیاری هستند، مگر اینکه خلاف آن ذکر شده باشد. این پیوند URL API را ساده می کند و به طور کلی زمانی توصیه می شود که با پیکربندی منبع داده الگو آشنا باشید و فقط می خواهید زیرمجموعه ای از پارامترها را لغو کنید. |
|
پارامترهای مورد نیاز هنگام تنظیم ds.connector
اگر پارامتر ds.connector
منبع داده مشخص شده باشد، تمام پارامترهای رابط تعیین شده به عنوان Required باید برای منبع داده مشخص شوند. اگر پارامتر 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 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، میتوانید با اطمینان از رعایت همه شرایط زیر، منبع داده را از گزارش الگوی خود دوباره اضافه کنید:
- منبع داده قابل استفاده مجدد است ( به منابع داده جاسازی شده در مقابل قابل استفاده مجدد مراجعه کنید)
- url منبع داده را با نام مستعار ارجاع نمی دهد
- نشانی اینترنتی از نام مستعار عام استفاده نمیکند (به منبع اطلاعات مستعار وایلدکارد مراجعه کنید)
هنگامی که یک منبع داده جدید با Linking API ایجاد می شود، از اعتبار کاربری استفاده می کند که روی URL کلیک کرده است. این بدان معناست که کاربر باید به داده های اساسی دسترسی داشته باشد وگرنه اتصال کار نخواهد کرد. با افزودن مجدد منبع داده به گزارش جدید تولید شده، می توانید اعتبار آن را حفظ کنید تا کاربران بتوانند به دسترسی به داده ها در گزارش های جدید خود ادامه دهند.
منبع داده مستعار wildcard
برای اعمال یک پارامتر Linking API به چندین منبع داده، میتوان از نام مستعار 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.*
، می توانید از این 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
تنظیم شود و شناسه جدول را برای پرس و جو ارائه کنید.
نام پارامتر | شرح |
---|---|
اختیاری. برای اتصال BigQuery روی bigQuery تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی BigQuery ارائه شده جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** نوع پرس و جو. روی TABLE تنظیم کنید. | |
مورد نیاز ** شناسه پروژه جدول برای پرس و جو. | |
مورد نیاز ** شناسه مجموعه داده جدول برای پرس و جو. | |
الزامی ** شناسه جدول جدول برای پرس و جو. جداول خرد شده تاریخ : * (کاراکتر عام) یا پسوند YYYYMMDD هنگام جستجو در جداول خرد شده تاریخ پشتیبانی می شود.اگر جدولی بهعنوان Google Analytics، Firebase Analytics یا Firebase Crashlytics شناسایی شود، یک الگوی فیلدهای پیشفرض انتخاب میشود مگر اینکه یکی از آنها مشخص شده باشد. پارامترهای مربوط به جدول الگوی فیلدها را ببینید. | |
اختیاری. شناسه پروژه برای استفاده برای صورتحساب. اگر تنظیم نشود، projectId استفاده خواهد شد. | |
اختیاری. اگر جدول پارتیشن بندی شده است و می خواهید از ستون پارتیشن بندی به عنوان بعد محدوده تاریخ استفاده کنید، روی true تنظیم کنید. این فقط برای پارتیشن بندی مبتنی بر زمان (به عنوان مثال استفاده از ستون پارتیشن بندی مبتنی بر زمان یا شبه ستون _PARTITIONTIME ) قابل استفاده است و برای جداول پارتیشن بندی شده با محدوده صحیح کار نمی کند. در صورت نامشخص بودن، پیش فرض به false می شود. برای کسب اطلاعات بیشتر به مقدمه جداول پارتیشن بندی شده مراجعه کنید. | |
اختیاری. در صورت نامشخص بودن، پیشفرض true است. برای جزئیات بیشتر به refreshFields مراجعه کنید. |
قالب فیلدها برای Google Analytics، Firebase Analytics و Crashlytics
برای جداول شناسایی شده به عنوان Google Analytics، Firebase Analytics، یا Firebase Crashlytics، پارامترهای اضافی برای تنظیم قالب فیلدها در دسترس هستند. اگر مشخص نشده باشد، یک الگوی پیش فرض انتخاب خواهد شد.
نام | شرح |
---|---|
اختیاری. الگوی فیلدهای Google Analytics برای استفاده. فقط زمانی قابل اجرا است که یک صادرات BigQuery برای جدول Google Analytics در حال درخواست است. یکی از ALL , SESSION , HITS . برای جداول Google Analytics، در صورت نامشخص بودن، به طور پیش فرض روی ALL قرار می گیرد. | |
اختیاری. الگوی فیلدهای Firebase Analytics برای استفاده. فقط زمانی که یک Export BigQuery برای جداول Firebase Analytics در حال درخواست است، قابل اجرا است. فقط روی EVENTS قابل تنظیم است. برای جداول Firebase Analytics، در صورت نامشخص بودن، EVENTS پیشفرض است. | |
قالب فیلدهای Firebase Crashlytics برای استفاده. فقط می تواند روی DEFAULT تنظیم شود. فقط زمانی اعمال میشود که صادر کردن BigQuery برای جدول Firebase Crashlytics در حال درخواست باشد. برای جداول Firebase Crashlytics، اگر مشخص نشده باشد، پیشفرض روی DEFAULT قرار میگیرد. |
پرس و جوهای سفارشی
پارامترهای زیر زمانی قابل اعمال هستند که type
بر روی CUSTOM_QUERY
تنظیم شده باشد و شما یک دستور SQL برای پرس و جو از جدول ارائه دهید.
نام پارامتر | شرح |
---|---|
اختیاری. برای اتصال BigQuery روی bigQuery تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی BigQuery ارائه شده جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** نوع پرس و جو. روی CUSTOM_QUERY تنظیم کنید. | |
مورد نیاز ** پرس و جوی SQL برای اجرا. | |
اختیاری. شناسه پروژه برای استفاده برای صورتحساب. اگر تنظیم نشود، projectId استفاده خواهد شد. اگر projectId تنظیم نشده باشد، از پروژه جدول پرس و جو استفاده می شود. | |
اختیاری. لیستی از الگوها و رشتههای جایگزین با کاما برای اعمال به پرس و جوی SQL. جایگزینی رشته فقط در صورتی اعمال می شود که مطابقت الگو وجود داشته باشد. از یک کاما برای جداسازی الگوها و جایگزینی جفت رشته ها استفاده کنید. به عنوان مثال، | |
اختیاری. در صورت نامشخص بودن، پیشفرض 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 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
آچار ابری
نام پارامتر | شرح |
---|---|
اختیاری. برای رابط Cloud Spanner روی cloudSpanner تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی Cloud Spanner ارائه شده جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** شناسه پروژه. | |
الزامی ** شناسه نمونه. | |
الزامی ** شناسه پایگاه داده. | |
مورد نیاز ** پرس و جوی SQL برای اجرا. | |
اختیاری. در صورت نامشخص بودن، پیشفرض 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
اتصالات جامعه
نام پارامتر | شرح |
---|---|
اختیاری. برای یک رابط انجمن روی community تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی Connector Community ارائه شده جایگزین میکند. Replace vs update را ببینید. | |
مورد نیاز ** connectorId Connector Community (همچنین به عنوان deploymentId شناخته می شود). | |
اختیاری. پارامترهای اضافی مخصوص اتصال دهنده، همانطور که توسط پیکربندی رابط اتصال دهنده جامعه تعریف شده است. | |
اختیاری. در صورت نامشخص بودن، پیشفرض به 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 Analytics روی googleAnalytics تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی ارائه شده Google Analytics جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** شناسه حساب. | |
الزامی ** شناسه ملک. | |
شناسه View. مورد نیاز ** برای ویژگی های Universal Analytics. ویژگی های Google Analytics 4 را تنظیم نکنید. | |
اختیاری. در صورت نامشخص بودن، پیش فرض به false می شود. برای جزئیات بیشتر به refreshFields مراجعه کنید. |
مثال ها
یک پیکربندی Google Analytics برای یک ویژگی 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 Analytics برای ویژگی Google Analytics 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
نام پارامتر | شرح |
---|---|
اختیاری. روی googleCloudStorage رابط Google Cloud Storage تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی Google Cloud Storage ارائه شده جایگزین میکند. Replace vs update را ببینید. | |
الزامی ** نوع مسیر. از FILE برای انتخاب یک فایل یا FOLDER برای انتخاب همه فایل ها برای مسیر داده شده استفاده کنید. | |
مورد نیاز ** مسیر فایل (به عنوان مثال MyBucket/MyData/MyFile.csv ) اگر pathType FILE باشد یا مسیر پوشه (مثلا *MyBucket/MyData ) اگر pathType FOLDER باشد. | |
اختیاری. در صورت نامشخص بودن، پیشفرض به 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 Sheets
نام پارامتر | شرح |
---|---|
اختیاری. برای رابط کاربرگنگار Google روی googleSheets تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی ارائه شده Google Sheets جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** شناسه صفحه گسترده. | |
الزامی ** شناسه کاربرگ. | |
اختیاری. برای استفاده از ردیف اول به عنوان سرصفحه، روی true تنظیم کنید. در صورت نامشخص بودن، پیشفرض true است. سرصفحه های ستون باید منحصر به فرد باشد. ستون هایی با هدر خالی به منبع داده اضافه نمی شوند. | |
اختیاری. برای گنجاندن سلول های مخفی روی true تنظیم کنید. در صورت نامشخص بودن، پیشفرض true است. | |
اختیاری. برای گنجاندن سلول های فیلتر شده روی true تنظیم کنید. در صورت نامشخص بودن، پیشفرض true است. | |
اختیاری. محدوده، به عنوان مثال A1:B52. | |
اختیاری. در صورت نامشخص بودن، پیشفرض true است. برای جزئیات بیشتر به refreshFields مراجعه کنید. |
مثال ها
یک پیکربندی Google Sheets:
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
نگاه کننده
نام پارامتر | شرح |
---|---|
اختیاری. روی جستجوگر رابط Looker looker کنید.در صورت تنظیم، منبع داده را با پیکربندی Looker ارائه شده جایگزین می کند. Replace vs update را ببینید. | |
مورد نیاز ** URL نمونه Looker. | |
مورد نیاز ** مدل Looker. | |
مورد نیاز ** The Looker Explore. | |
اختیاری. در صورت نامشخص بودن، پیش فرض به false می شود. برای جزئیات بیشتر به refreshFields مراجعه کنید. |
مثال
اتصال به یک Looker Explore:
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 روی searchConsole تنظیم کنید.در صورت تنظیم، منبع داده را با پیکربندی کنسول جستجوی ارائه شده جایگزین می کند. Replace vs update را ببینید. | |
الزامی ** آدرس سایت. برای یک ویژگی Domain ، پیشوند sc-domain\: . | |
مورد نیاز ** نوع جدول را تنظیم می کند. می تواند یکی از SITE_IMPRESSION یا URL_IMPRESSION باشد. | |
مورد نیاز ** نوع جستجو را تنظیم می کند. می تواند یکی از WEB , IMAGE , VIDEO یا NEWS باشد . | |
اختیاری. در صورت نامشخص بودن، پیش فرض به 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 برای منبع داده | توصیه برای مجوزهای منبع داده | یادداشت |
---|---|---|---|
تعبیه شده است | جایگزین کردن | N/A - دسترسی به نمایش از گزارش به ارث می رسد. | اگر کاربر به گزارش الگو دسترسی مشاهده داشته باشد، به طور خودکار به هر منبع داده جاسازی شده دسترسی خواهد داشت. |
تعبیه شده است | به روز رسانی | N/A - دسترسی به نمایش از گزارش به ارث می رسد. | اگر کاربر به گزارش الگو دسترسی مشاهده داشته باشد، به طور خودکار به هر منبع داده جاسازی شده دسترسی خواهد داشت. |
قابل استفاده مجدد | جایگزین کردن | کاربران نیازی به دسترسی به نمایش ندارند. | از آنجایی که پیکربندی منبع داده به طور کامل از طریق Linking API جایگزین می شود، دسترسی به مشاهده لازم نیست. |
قابل استفاده مجدد | به روز رسانی | کاربر نیاز به دسترسی به مشاهده دارد. | دسترسی مشاهده به منبع داده برای پیوند API لازم است تا بتواند پیکربندی را از منبع داده الگو بخواند و از آن استفاده کند. اگر کاربران دسترسی به مشاهده نداشته باشند هنگام بارگیری گزارش با خطا مواجه می شوند. |
از یک گزارش خالی یا پیش فرض استفاده کنید
برای استفاده از گزارش خالی یا گزارش پیشفرض، Linking API خود را به صورت زیر پیکربندی کنید:
نوع گزارش | پارامتر کنترل reportId را تنظیم کنید | پارامترهای منبع داده ( ) را تنظیم کنید. | یادداشت |
---|---|---|---|
گزارش خالی | خیر | خیر | |
گزارش پیش فرض | خیر | آره | گزارش پیش فرض توسط Looker Studio ارائه شده است. هنگام تعیین پارامترهای منبع داده برای گزارش پیش فرض، نیازی به استفاده از نام مستعار منبع داده نیست، زیرا گزارش پیش فرض دارای یک منبع داده جاسازی شده است. |
مثالهای زیر نشانیهای اینترنتی مختلف 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 جاسازی API پیوند دهنده باید به شکل زیر باشد:
https://lookerstudio.google.com/embed/reporting/create?parameters
شناسه و نام مستعار را پیدا کنید
شناسه گزارش
برای یافتن شناسه گزارش:
- گزارشی را که می خواهید به عنوان الگو استفاده کنید باز کنید. URL گزارش را بررسی کنید. قسمت بین
reporting/
و/page
شناسه گزارش است. به عنوان مثال، در URL زیر،0B_U5RNpwhcE6SF85TENURnc4UjA
شناسه گزارش است:
https://lookerstudio.google.com/reporting/0B_U5RNpwhcE6SF85TENURnc4UjA/page/1M
نام مستعار منبع داده
یک گزارش می تواند چندین منبع داده داشته باشد. منبع داده باید با نام مستعار ارجاع داده شود.
برای یافتن نام مستعار منبع داده:
- گزارش را ویرایش کنید
- از نوار ابزار، Resource > Manage Added Data Sources را انتخاب کنید.
- ستون Alias را برای یافتن اطلاعات نام مستعار برای هر منبع داده بررسی کنید.
میتوانید نامهای مستعار را ویرایش کنید تا هنگام اضافه یا حذف منبع داده، از سازگاری با عقب اطمینان حاصل کنید.
نوع رابط
یک گزارش می تواند چندین منبع داده داشته باشد که هر کدام با پیکربندی یک رابط ایجاد می شوند. برای پیدا کردن نوع رابط مورد استفاده برای ایجاد منبع داده:
- گزارش را ویرایش کنید
- از نوار ابزار، Resource > Manage Added Data Sources را انتخاب کنید.
- ستون Connector Type را برای شناسایی رابط مورد استفاده برای ایجاد منبع داده بررسی کنید.
نکات و عیب یابی
اگر مشکل دارید، جزئیات زیر را مرور کنید تا مشکلات احتمالی و پیکربندیهای اشتباه رایج را شناسایی کنید.
دیالوگ اشکال زدایی
از گفتگوی اشکال زدایی برای بررسی پیکربندی Linking API همانطور که توسط Looker Studio تفسیر شده است استفاده کنید. می تواند به رفع اشکالات با API کمک کند.
- هنگامی که در هنگام تجزیه URL API پیوند دهنده با خطایی مواجه میشوید، یک گفتگو به طور خودکار با جزئیات مربوط به خطا نمایش داده میشود.
- هنگامی که خطایی رخ می دهد و هیچ گفتگویی به طور خودکار نمایش داده نمی شود، به دنبال دکمه اطلاعات در سمت راست بالای گزارش بگردید. برای اطلاعات بیشتر در مورد اشکال زدایی کلیک کنید.
- اگر دکمه اطلاعات در دسترس نیست، میتوانید با افزودن پارامتر
&c.explain=true
به انتهای هر URL API پیوند دادن، دکمه را فعال کنید.
مجوزها
مطمئن شوید که مجوزهای الگو را برای انواع منبع داده و پیکربندی Linking API تنظیم کردهاید. برای جزئیات بیشتر به مجوزهای الگو مراجعه کنید.
به روز رسانی در مقابل جایگزینی
اگر پیکربندی منبع داده را از الگوی منبع داده بهروزرسانی میکنید، پیکربندی منبع داده الگو و پیکربندی Linking API را بررسی کنید تا مطمئن شوید که سازگار هستند. تأیید کنید که فیلدهای به دست آمده از پیکربندی جدید با اجزای گزارش و پیکربندی سازگار هستند.
هنگام انجام بهروزرسانی در مقابل جایگزینی، میتوان یک پیکربندی نامعتبر با رفتار نامشخص تنظیم کرد. برای جزئیات بیشتر Replace vs update را ببینید.
بازخوانی فیلدها
اگر نام فیلدها، انواع یا تجمیعهایی را برای منبع داده الگو پیکربندی کردهاید، این تغییرات تنها در صورتی به منبع داده پیکربندیشده Linking API منتقل میشود که پارامتر ds.refreshFields
روی false
تنظیم شود.
پارامتر منبع داده ds.refreshFields
URL API Linking خود را مرور کنید. در صورت حذف، تأیید کنید که مقدار پیشفرض پارامتر برای هر نوع رابط برای مورد استفاده شما صحیح است.
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.
Feedback and support
Use the Issue Tracker to report Linking API issues or to provide feedback. See Support for general resources on getting help and asking questions.
Changelog
2023-06-06
- Added
r.measurementId
andr.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
2023-05-22
- 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 whentype
is set toCUSTOM_QUERY
. - When
billingProjectId
is not set then the billing project will fallback toprojectId
or the project of the queried table. - Added support for date partitioned tables. Set the
isPartitioned
parameter totrue
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 totrue
, consistent with the web UI default. -
includeHiddenAndFilteredCell
split intoincludeHiddenCells
and -
includeFilteredCells
. Both now default totrue
, consistent with the web UI default.
-
- Search Console connector
- Renamed the
propertyType
parameter tosearchType
.
- Renamed the
- Surveys connector
-
surveyId
now accepts a single survey ID or a comma-separated list of survey IDs.
-
2021-12-16
- 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.