مرجع کتابخانه Looker Studio Community Component (dscc).

توجه: ویژگی تجسم جامعه در «پیش‌نمایش توسعه‌دهندگان» است. برای کسب اطلاعات بیشتر در مورد ویژگی‌ها و بهبودهای آینده در این دوره، از صفحه پیش‌نمایش توسعه‌دهندگان دیدن کنید.

نمای کلی API

dscc (مخفف Looker Studio Community Component) کتابخانه‌ای است که به ساخت کامپوننت‌های Community برای Looker Studio کمک می‌کند. کد منبع را می‌توانید در GitHub پیدا کنید.

dscc سه تابع را در اختیار قرار می‌دهد: getWidth() ، getHeight() و subscribeToData() .

getWidth()

نام	پارامترها	نوع بازگشتی	توضیحات
تابع getWidth()	هیچکدام	number	عرض iframe را بر حسب پیکسل برمی‌گرداند.

استفاده از getWidth()

// to get the width of the iframe
var width = dscc.getWidth();

getHeight()

نام	پارامترها	نوع بازگشتی	توضیحات
دریافت ارتفاع ()	هیچکدام	int	ارتفاع iframe را بر حسب پیکسل برمی‌گرداند.

استفاده از getHeight()

// to get the height of the iframe
var height = dscc.getHeight();

ارسال تعامل()

تابع sendInteraction() پیامی حاوی داده‌های مربوط به یک فیلتر را به Looker Studio ارسال می‌کند.

پارامترها:

نام	نوع	توضیحات
شناسه اقدام	string	رشته‌ای که با actionId در فایل پیکربندی مطابقت دارد
تعامل	enum(InteractionType)	درباره تعامل با استودیو Looker Studio صحبت می‌کند
داده‌ها	object(InteractionData)	داده‌های مورد نیاز برای تعامل را فراهم می‌کند

InteractionType

در حال حاضر، تنها InteractionType معتبر، FILTER است.

نام	نوع	توضیحات
فیلتر نوع تعامل dscc	شمارشی	تعامل FILTER را شرح می‌دهد

استفاده از sendInteraction

// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";

// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;

var fieldID = "qt_m9dtntutsb";
var dataValue = "Asia";

// sendInteraction expects data that tells you the concepts and the values of
// those concepts to use in constructing a filter.
var interactionData = {
  "concepts": [fieldId],
  "values": [[dataValue]]
}

dscc.sendInteraction(actionId, FILTER, interactionData);

interactionData

var interactionData = {
  "concepts": array(fieldId),
  "values": array(array(dataValue))
}

میدان	نوع	توضیحات
مفاهیم	Array	آرایه‌ای از fieldIds
ارزش‌ها	Array<Array>	آرایه‌ای تو در تو از مقادیر داده. هر زیرآرایه باید به اندازه طول آرایه concepts باشد. هر مقدار در زیرآرایه مربوط به یک مقدار بُعد است.

نمونه interactionData :

var interactionData = {
  "concepts": ["dim1Id", "dim2Id"],
  "values": [
    ["dim1Val1", "dim2Val1"],
    ["dim1Val2", "dim2Val2"]
    ]
}

استفاده از dscc.sendInteraction به همراه interactionData فوق معادل دستور SQL زیر است:

SELECT data WHERE
  (dim1 == dim1Val1 AND dim2 == dim2Val1)
  OR
  (dim1 == dim1Val2 AND dim2 == dim2Val2);

تابع ()clearInteraction

تابع clearInteraction() پیامی را به Looker Studio ارسال می‌کند تا فیلتری را که قبلاً توسط این تجسم تنظیم شده است، پاک کند.

پارامترها:

نام	نوع	توضیحات
شناسه اقدام	string	رشته‌ای که با actionId در فایل پیکربندی مطابقت دارد
تعامل	enum(InteractionType)	درباره تعامل با استودیو Looker می‌گوید

استفاده از clearInteraction()

// the actionID can either be hardcoded or parsed from the returned data
var actionId = "interactionConfigId";

// dscc provides enums for the interaction types
var FILTER = dscc.InteractionType.FILTER;

dscc.clearInteraction(actionId, FILTER);

subscribeToData(callback, options)

subscribeToData() پیام‌های دریافتی از Looker Studio را دریافت می‌کند.

پارامترها:

نام	نوع	توضیحات
فراخوانی برگشتی (داده)	function	تابعی که داده‌های برگردانده شده توسط subscribeToData را دریافت می‌کند.
گزینه‌ها	object	قالب بازگشت داده مورد نظر را تعریف می‌کند

شیء options به شکل زیر است:

{
  transform: dscc.tableTransform | dscc.objectTransform
}

مقدار بازگشتی:

نوع	توضیحات
function	لغو اشتراک callback از پیام‌های بعدی Looker Studio

استفاده از subscribeToData()

// define and use a callback
var unsubscribe = dscc.subscribeToData(function(data){
  // console.log the returned data
  console.log(data);
}, {transform: dscc.tableTransform});

// to unsubscribe

unsubscribe();

data

این شیء به تابع callback ثبت‌شده با dscc.subscribeToData ارسال می‌شود. فیلدهای زیر بین dscc.objectFormat و dscc.tableFormat مشترک هستند.

{
  fields: object(fieldsByConfigId),
  style: object(styleById),
  interactions: object(interactionsById),
  theme: object(themeStyle),
  tables: object(tablesById),
  dateRanges: object(dateRangesById)
}

میدان	نوع	توضیحات
زمینه‌ها	object(fieldsByConfigId)	شیء‌ای که شامل فیلدهایی است که توسط configId آنها ایندکس شده‌اند.
سبک	object(styleById)	شیء‌ای که شامل اشیاء استایل است که توسط configId خود ایندکس شده‌اند.
تعاملات	object(interactionsById)	شیء‌ای که شامل اشیاء تعاملی است
تم	themeStyle	یک شیء themeStyle که حاوی اطلاعات استایل‌بندی تم برای گزارش است.
میزها	object(tablesById)	شیء‌ای که شامل tableObjects است
محدوده‌های تاریخ	object(dateRangesById)	یک شیء که شامل dateRanges است

فیلدهای ByConfigId

{
   configId: array(field)
}

شیء fieldsByConfigId شامل آرایه‌هایی از اشیاء فیلد است که توسط "id" تعریف شده در پیکربندی تجسم، اندیس‌گذاری شده‌اند. برای هر dataField تعریف شده در پیکربندی، یک ورودی در این شیء وجود دارد.

میدان	نوع	توضیحات
شناسه پیکربندی	Array<field>	آرایه‌ای از فیلد(ها) مرتبط با dataField

میدان

{
  id: fieldId,
  name: string,
  description: string,
  type: fieldType,
  concept: enum(conceptType)
}

شیء field ، اطلاعاتی در مورد فیلدی که کاربر در پنل ویژگی‌ها انتخاب می‌کند، ارائه می‌دهد.

میدان	نوع	توضیحات
شناسه	string	استودیوی Looker برای این فیلد شناسه ایجاد کرد.
نام	string	نام فیلد قابل خواندن توسط انسان
توضیحات	string	شرح میدان
نوع	enum(fieldType)	نوع معنایی فیلد
مفهوم	enum(conceptType)	مفهوم نوع فیلد

سبک توسط شناسه

{
   configId: styleValue
}

شیء styleById اطلاعات سبکی را که توسط "id" تعریف شده در پیکربندی تجسم فهرست بندی شده است، ارائه می‌دهد.

میدان	نوع	توضیحات
شناسه پیکربندی	styleValue	یک شیء که شامل مقدار style و مقدار style پیش‌فرض تعریف‌شده توسط پیکربندی است.

سبکمقدار

{
  value: string | object | bool | number,
  defaultValue: string | object | bool | number
}

شیء styleValue هم مقدار سبک انتخاب شده توسط کاربر و هم مقدار پیش‌فرض تعریف شده در پیکربندی را ارائه می‌دهد. نوع value و defaultValue به عنصر style بستگی دارد.

میدان	نوع	توضیحات
ارزش	string OR object OR bool OR number	مقدار عنصر سبک که از انتخاب کاربر در پنل ویژگی‌ها برگردانده می‌شود
مقدار پیش‌فرض	string OR object OR bool OR number	مقدار پیش‌فرض عنصر style که در پیکربندی تجسم تعریف شده است

تعاملات با شناسه

{

}

شیء interactionsById داده‌های تعاملی را که توسط پیکربندی تجسم interactionId فهرست‌بندی شده‌اند، ارائه می‌دهد.

فهرست	نوع	توضیحات
شناسه پیکربندی	interaction	شیء‌ای که حاوی داده‌های مرتبط با یک تعامل است

فیلد تعاملی

{
  value: object(interactionValue),
  supportedActions: array(InteractionType)
}

شیء interactionField شامل آرایه‌ای از supportedActions تعریف شده در پیکربندی و همچنین مقادیر انتخاب شده توسط کاربر برای تعامل است.

میدان	نوع	توضیحات
ارزش	string OR object OR bool OR number	مقدار عنصر سبک که از انتخاب کاربر در پنل ویژگی‌ها برگردانده می‌شود
اقدامات پشتیبانی‌شده	Array<InteractionType>	اقدامات پشتیبانی شده توسط این تعامل، همانطور که در پیکربندی تعریف شده است

ارزش تعاملی

شیء interactionValue مقادیر انتخاب شده توسط کاربر را برای نوع تعامل ارائه می‌دهد. اگر کلید data وجود داشته باشد، شیء InteractionData وضعیت فعلی فیلتر را منعکس می‌کند. اگر کلید data وجود نداشته باشد، تجسم در حال حاضر به عنوان یک فیلتر پیکربندی نشده است.

{
  type: enum(InteractionType)
  data: object(interactionData) | None
}

میدان	نوع	توضیحات
نوع	enum(InteractionType)	نوع تعامل انتخاب شده توسط کاربر
داده‌ها	object(InteractionData)	داده‌های مرتبط با وضعیت فعلی فیلتر. اگر فیلتر در حال حاضر پاک شده باشد، این کلید وجود نخواهد داشت.

تم

{
  fillColor: {
    color: string,
    opacity: number
  },
  fontColor: {
    color: string,
    opacity: number
  },
  accentFillColor: {
    color: string,
    opacity: number
  },
  accentFontColor: {
    color: string,
    opacity: number
  },
  fontFamily: string,
  accentFontFamily: string,
  increaseColor: {
    color: string,
    opacity: number
  },
  decreaseColor: {
    color: string,
    opacity: number
  },
  gridColor: {
    color: string,
    opacity: number
  },
  seriesColor: [
    {
      color: string,
      opacity: number
    }
  ]
}

شیء themeStyle اطلاعات مربوط به قالب گزارش را به تجسم‌سازی ارسال می‌کند.

میدان	نوع	توضیحات
رنگ را پر کنید	object	یک شیء با فرمت {color: string, opacity: number}
رنگ فونت	object	یک شیء با فرمت {color: string, opacity: number}
رنگ پر کننده لهجه	object	یک شیء با فرمت {color: string, opacity: number}
رنگ فونت accent	object	یک شیء با فرمت {color: string, opacity: number}
خانواده فونت	string	رشته‌ای که خانواده فونت را توصیف می‌کند
خانواده فونت اکسنت	string	رشته‌ای که خانواده فونت accent را توصیف می‌کند
افزایش رنگ	object	یک شیء با فرمت {color: string, opacity: number}
کاهشرنگ	object	یک شیء با فرمت {color: string, opacity: number}
رنگ شبکه‌ای	object	یک شیء با فرمت {color: string, opacity: number}
سریرنگ	Array<object>	آرایه‌ای از اشیاء با فرمت {color: string, opacity: number}

جداول با شناسه

{
  "DEFAULT": object(tableObject),
  "COMPARISON": object(tableObject) | undefined
}

tableObject اطلاعات عنوان و داده‌ها را برای هر ردیف ارائه می‌دهد. "DEFAULT" همیشه داده‌ها را برمی‌گرداند و "COMPARISON" فقط در صورتی پر می‌شود که کاربر داده‌ها را با ردیف‌های مقایسه پیکربندی کند.

تنها تفاوت بین dscc.tableFormat و dscc.objectFormat فرمت tableObject است.

میدان	نوع	توضیحات
"پیش‌فرض"	object(tableObject) OR Array<objectRow>	tableObject مرتبط با داده‌هایی که کاربر به یک تجسم اضافه می‌کند
«مقایسه»	object(tableObject) OR Array<objectRow>	tableObject مرتبط با داده‌های مقایسه تاریخ ، در صورت وجود

محدوده‌های تاریخ بر اساس شناسه

{
  "DEFAULT": object(dateRange),
  "COMPARISON": object(dateRange)
}

شیء dateRangesById اطلاعاتی در مورد محدوده‌های تاریخ پیش‌فرض و مقایسه‌ای ارائه می‌دهد. اگر هیچ محدوده تاریخی وجود نداشته باشد، شیء خالی خواهد بود. DEFAULT و COMPARISON فقط در صورتی پر می‌شوند که محدوده‌های تاریخ مربوطه توسط کاربر پیکربندی شده باشند. داده‌های موجود در محدوده‌های تاریخ مربوط به داده‌های پیش‌فرض و مقایسه‌ای هستند که در tablesById تعریف شده‌اند.

میدان	نوع	توضیحات
"پیش‌فرض"	object(dateRange)	dateRange مرتبط با محدوده تاریخ پیش‌فرض، در صورت وجود.
«مقایسه»	object(dateRange)	dateRange مرتبط با محدوده تاریخ مقایسه، در صورت وجود.

محدوده تاریخ

{
  start: string,
  end: string
}

شیء dateRange اطلاعاتی در مورد تاریخ شروع و پایان یک محدوده تاریخ پیش‌فرض یا مقایسه‌ای ارائه می‌دهد.

میدان	نوع	توضیحات
شروع	string	تاریخ شروع محدوده تاریخ با فرمت YYYYMMDD.
پایان	string	تاریخ پایان محدوده تاریخ با فرمت YYYYMMDD.

مرجع tableFormat

شیء جدولی

{
  headers: array(object),
  rows: array(array)
}

میدان	نوع	توضیحات
سربرگ‌ها	Array	آرایه‌ای از اشیاء فیلدها . این اشیاء فیلد علاوه بر این، دارای یک ویژگی configId هستند که با شناسه‌های موجود در فایل پیکربندی مطابقت دارد.
ردیف‌ها	Array<Array>	آرایه‌ای از آرایه‌ها: هر آرایه یک ردیف از داده‌ها است

نمونه داده های tableFormat

این یک نمونه data است که با استفاده از dscc.subscribeToData() با گزینه dscc.tableFormat برگردانده شده است.

{
  "tables": {
    "DEFAULT": {
      "headers": [{
        "id": "qt_ky8sltutsb",
        "name": "dimension",
        "type": "TEXT",
        "concept": "DIMENSION",
        "configId": "configId1"
      }, {
        "id": "qt_b5bvmtutsb",
        "name": "second dim",
        "type": "TEXT",
        "concept": "DIMENSION"
        "configId": "configId1"
      }, {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC",
        "configId": "configId2"
      }],
      "rows": [
        ["Week 4", "lm", 55]
      ]
    },
    "COMPARISON": {
      "headers": [{
        "id": "qt_ky8sltutsb",
        "name": "dimension",
        "type": "TEXT",
        "concept": "DIMENSION",
        "configId": "configId1"
      }, {
        "id": "qt_b5bvmtutsb",
        "name": "second dim",
        "type": "TEXT",
        "concept": "DIMENSION"
        "configId": "configId1"
      }, {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC",
        "configId": "configId2"
      }],
      "rows": [
        ["Week 5", "no", 123]
      ]
    }
  },
  "fields": {
    "configId1": [
      {
        "id": "qt_ky8sltutsb",
        "name": "week",
        "type": "TEXT",
        "concept": "DIMENSION"
      },
      {
        "id": "qt_b5bvmtutsb",
        "name": "textId",
        "type": "TEXT",
        "concept": "DIMENSION"
      }
    ],
    "configId2": [
      {
        "id": "qt_m9dtntutsb",
        "name": "orders",
        "type": "NUMBER",
        "concept": "METRIC"
      }
    ]
  },
  "style": {
    "nodeColor": {
      "value": {
        "color": "#000000"
      }
    }
  },
  "theme": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "interactions": {
    "onClick": {
      "value": {
        "type": "FILTER",
        "data": {
          "concepts": [
            "qt_h6oibrb6wb",
            "qt_i6oibrb6wb"
          ],
          "values": [
            [
              "Afternoon",
              "Sunday"
            ],
            [
              "Afternoon",
              "Thursday"
            ],
            [
              "Morning",
              "Tuesday"
            ]
          ]
        }
      },
      "supportedActions": [
        "FILTER"
      ]
    }
  }
}

مرجع objectFormat

ردیف شیء

{
  configId1: array(string | bool | number),
  configId2: array(string | bool | number)
}

میدان	نوع	توضیحات
شناسه پیکربندی	آرایه	آرایه‌ای از مقادیر مرتبط با یک شناسه پیکربندی خاص

نمونه شیءداده قالب‌بندی

این یک نمونه data است که با استفاده از dscc.subscribeToData() با گزینه dscc.objectFormat برگردانده شده است.

{
  "tables": {
    "COMPARISON": [
      {
        "configId1": ["Week 5", "cd"],
        "configId2": [123]
      }
    ],
    "DEFAULT": [
      {
        "configId1": ["Week 1", "ab"],
        "configId2": [24]
      }
    ]
  },
  "fields": {
    "configId1": [
      {
        "id": "qt_h6oibrb6wb",
        "name": "time of day",
        "type": "TEXT",
        "concept": "DIMENSION"
      },
      {
        "id": "qt_i6oibrb6wb",
        "name": "day",
        "type": "TEXT",
        "concept": "DIMENSION"
      }
    ],
    "configId2": [
      {
        "id": "qt_m9dtntutsb",
        "name": "metric",
        "type": "NUMBER",
        "concept": "METRIC"
      }
    ]
  },
  "style": {
    "nodeColor": {
      "value": {
        "color": "#000000"
      }
    }
  },
  "theme": {},
  "dateRanges": {
    "DEFAULT": {
      "start": "20210501",
      "end": "20210531"
    },
    "COMPARISON": {
      "start": "20200501",
      "end": "20200531"
    }
  },
  "interactions": {
    "onClick": {
      "value": {
        "type": "FILTER",
        "data": {
          "concepts": [
            "qt_h6oibrb6wb",
            "qt_i6oibrb6wb"
          ],
          "values": [
            [
              "Afternoon",
              "Sunday"
            ],
            [
              "Afternoon",
              "Thursday"
            ],
            [
              "Morning",
              "Tuesday"
            ]
          ]
        }
      },
      "supportedActions": [
        "FILTER"
      ]
    }
  }
}