1. Wprowadzenie
Studio danych umożliwia bezpłatne tworzenie aktywnych, interaktywnych paneli z atrakcyjnymi wizualizacjami danych. Pobieraj dane z różnych źródeł i twórz w Studio danych nieograniczoną liczbę raportów z pełnymi możliwościami edycji i udostępniania. Poniższy zrzut ekranu przedstawia przykładowy panel Studia danych:
( Kliknij tutaj, aby wyświetlić ten przykładowy raport w Studio danych)
Społecznościowe oprogramowanie sprzęgające to funkcja Studia danych, która umożliwia tworzenie oprogramowania sprzęgającego dowolne źródło danych dostępne w internecie za pomocą Apps Script. Społecznościowe oprogramowanie sprzęgające jest tworzone przez społeczność Studia danych. Oznacza to, że każdy może tworzyć złącza społecznościowe. Możesz też udostępniać złącza społeczności innym osobom, aby mogły uzyskiwać dostęp do własnych danych w Studiu danych.
Z połączeń społecznościowych możesz korzystać w różnych przypadkach:
- wyświetlasz dane z platformy komercyjnej (np.mediów społecznościowych, marketingu, analityki itp.);
- wizualizujesz dane przedsiębiorstwa przechowywane lokalnie (np. dane o sprzedaży z lokalnej bazy danych MySQL);
- Udostępniasz klientom sposób wizualizacji danych z Twojej usługi.
- Tworzysz platformę raportowania za pomocą przycisku
- wizualizujesz własne dane ze źródła internetowego (np. tworzysz panel Google Fit);
Czego się nauczysz
- Jak działa społecznościowe oprogramowanie sprzęgające Studia danych
- Jak używać Google Apps Script do tworzenia społecznościowego oprogramowania sprzęgającego
- Jak korzystać ze społecznościowych oprogramowań sprzęgających w Studiu danych
Czego potrzebujesz
- dostęp do internetu i przeglądarki;
- konto Google,
- Znajomość podstaw języka JavaScript i interfejsów Web API
2. Krótka ankieta
Dlaczego wybierasz ten codelab?
Jak zamierzasz korzystać z tego laboratorium/samouczka?
Jak oceniasz swoją znajomość Studia danych?
Która opcja najlepiej opisuje Twoje wykształcenie?
Możesz przejść do następnej strony, aby przesłać informacje z ankiety.
3. Omówienie złączy społeczności
Złącza społeczności w Studiu danych umożliwiają bezpośrednie połączenia ze Studia danych z dowolnym źródłem danych dostępnym w internecie. Możesz łączyć się z platformami komercyjnymi, publicznymi zbiorami danych lub własnymi prywatnymi danymi lokalnymi. Złącza społeczności mogą pobierać dane za pomocą interfejsów API sieci, interfejsów API JDBC, plików płaskich (CSV, JSON, XML) i usług Apps Script.
Wyobraź sobie, że masz opublikowany pakiet w npm i chcesz śledzić liczbę pobrań pakietu w czasie z podziałem na dni. W tym ćwiczeniu utworzysz oprogramowanie sprzęgające społeczności, które pobiera dane za pomocą interfejsu API liczby pobrań pakietów npm. Oprogramowanie sprzęgające społeczności można następnie wykorzystać w Studio danych do utworzenia panelu, który wizualizuje liczbę pobrań.
4. Przepływ pracy w przypadku łącznika społecznościowego
W podstawowym łączniku społeczności definiujesz 4 funkcje:
getAuthType()getConfig()getSchema()getData()
W zależności od bieżącego kroku procesu Studio danych wykonuje te funkcje łącznika i wykorzystuje odpowiedź w kolejnych krokach. Na poniższym filmie znajdziesz omówienie tych kwestii:
- Jak działa złącze społecznościowe
- Różne etapy przepływu pracy
- Kiedy wywoływane są różne funkcje
- Kiedy Studio danych wyświetla różne interfejsy
- Oczekiwane działania użytkowników na różnych etapach
Po obejrzeniu filmu możesz wrócić do ćwiczenia.
Nie musisz zapamiętywać tego przepływu pracy. Wystarczy, że się z nim zapoznasz, aby zrozumieć, co się dzieje w przypadku konektora. Zawsze możesz wrócić do tego diagramu.
W następnym kroku zaczniesz tworzyć oprogramowanie sprzęgające w Google Apps Script. Będziesz musiał(a) przełączać się między interfejsem Apps Script a tym kursem.
5. Konfigurowanie projektu Apps Script
Krok 1. Otwórz stronę Google Apps Script.
Krok 2. Utwórz nowy projekt Apps Script, klikając „+ Nowy projekt” w lewym górnym rogu.
Zobaczysz projekt powłoki z pustą funkcją myFunction w pliku Code.gs.
Krok 3. Usuń funkcję myFunction.
Krok 4. Nadaj projektowi nazwę:
- W lewym górnym rogu strony kliknij
Untitled project. - Wpisz tytuł projektu.
Zacznij pisać kod oprogramowania sprzęgającego w pliku Code.gs.
6. Zdefiniuj funkcję getAuthType()
Gdy Studio danych będzie potrzebować informacji o metodzie uwierzytelniania używanej przez oprogramowanie sprzęgające, wywoła funkcję getAuthType(). Ta funkcja powinna zwracać metodę uwierzytelniania wymaganą przez oprogramowanie sprzęgające do autoryzacji usługi innej firmy.
W przypadku tworzonego przez Ciebie konektora pobierania npm nie musisz uwierzytelniać się w żadnej usłudze innej firmy, ponieważ używany przez Ciebie interfejs API nie wymaga uwierzytelniania. Skopiuj ten kod i dodaj go do pliku Code.gs:
Code.gs
var cc = DataStudioApp.createCommunityConnector();
function getAuthType() {
var AuthTypes = cc.AuthType;
return cc
.newAuthTypeResponse()
.setAuthType(AuthTypes.NONE)
.build();
}
W tym miejscu wskazujesz, że Twój łącznik nie wymaga uwierzytelniania przez podmiot zewnętrzny (AuthTypes.NONE). Aby zobaczyć wszystkie obsługiwane metody uwierzytelniania, zapoznaj się z dokumentacją AuthType().
7. Definiowanie funkcji getConfig()
Zanim użytkownicy będą mogli zacząć korzystać z Twojego łącznika, muszą go skonfigurować. Odpowiedź funkcji getConfig() określa opcje konfiguracji, które zobaczą użytkownicy. Studio danych wywołuje funkcję getConfig(), aby uzyskać szczegóły konfiguracji oprogramowania sprzęgającego. Na podstawie odpowiedzi podanej przez getConfig() Studio danych wyświetli ekran konfiguracji łącznika i zmieni niektóre jego zachowania.
Na ekranie konfiguracji możesz podawać informacje lub uzyskiwać dane wejściowe od użytkownika za pomocą tych elementów formularza:
| Element wejściowy | Pole tekstowe z jednym wierszem. |
| Element wejściowy | Wielowierszowe pole tekstowe. |
| Element wejściowy | Menu z opcjami jednokrotnego wyboru. |
| Element wejściowy | Menu z opcjami wielokrotnego wyboru. |
| Element wejściowy | Pojedyncze pole wyboru, które może służyć do przechwytywania wartości logicznych. |
| Element wyświetlany | Statyczne pole tekstowe, które może służyć do przekazywania użytkownikowi instrukcji lub informacji. |
Użyj elementu INFO, aby podać instrukcje dla użytkownika, a elementu TEXTINPUT, aby uzyskać od użytkownika nazwę pakietu wejściowego. W getConfig() odpowiedzi zgrupujesz te elementy formularza pod kluczem configParams.
Interfejs API, z którym się łączysz, wymaga daty jako parametru, więc w odpowiedzi getConfig() ustaw dateRangeRequired na true. Dzięki temu Studio danych będzie uwzględniać zakresy dat we wszystkich żądaniach danych. Jeśli źródło danych nie wymaga daty jako parametru, możesz ją pominąć.
Dodaj do pliku Code.gs ten kod getConfig() poniżej istniejącego kodu dla getAuthType():
Code.gs
function getConfig(request) {
var config = cc.getConfig();
config.newInfo()
.setId('instructions')
.setText('Enter npm package names to fetch their download count.');
config.newTextInput()
.setId('package')
.setName('Enter a single package name')
.setHelpText('e.g. googleapis or lighthouse')
.setPlaceholder('googleapis');
config.setDateRangeRequired(true);
return config.build();
}
Na podstawie tych parametrów konfiguracji, gdy użyjesz łącznika w Studio danych, zobaczysz ekran konfiguracji podobny do tego poniżej. Ale o tym opowiemy później.
Przejdźmy do następnej funkcji – getSchema().
8. Definiowanie funkcji getSchema()
Studio danych wywołuje funkcję getSchema(), aby uzyskać schemat powiązany z konfiguracją wybraną przez użytkownika dla łącznika. Na podstawie odpowiedzi podanej przez getSchema() Studio danych wyświetli użytkownikowi ekran pól z listą wszystkich pól w łączniku.
W przypadku każdej konfiguracji łącznika schemat to lista wszystkich pól, dla których łącznik może dostarczać dane. W zależności od konfiguracji łącznik może zwracać różne schematy z różnymi polami. Schemat może zawierać pola pobierane ze źródła interfejsu API, pola obliczane w Apps Script i pola obliczane w Data Studio za pomocą formuły pola obliczeniowego. Łącznik udostępnia metadane każdego pola w schemacie, w tym:
- Nazwa pola
- Typ danych pola
- Informacje semantyczne
Aby dowiedzieć się więcej, zapoznaj się z informacjami w sekcjach getSchema() i Field.
W zależności od sposobu pobierania danych przez łącznik schemat może być stały lub obliczany dynamicznie po wywołaniu funkcji getSchema(). Parametry konfiguracji z funkcji getConfig() zdefiniowane przez użytkownika będą przekazywane w argumencie request funkcji getSchema().
W tym ćwiczeniu nie musisz uzyskiwać dostępu do argumentu request. Więcej informacji o argumencie request znajdziesz w następnym segmencie, w którym będziesz pisać kod funkcji getData().
Schemat łącznika jest stały i zawiera te 3 pola:
| Nazwa pakietu npm podana przez użytkownika |
| Liczba pobrań pakietu npm |
| Data liczby pobrań |
Poniżej znajdziesz kod getSchema() konektora. Funkcja pomocnicza getFields() wyodrębnia tworzenie pól, ponieważ ta funkcja jest potrzebna zarówno w przypadku getSchema(), jak i getData(). Dodaj ten kod do pliku Code.gs:
Code.gs
function getFields(request) {
var cc = DataStudioApp.createCommunityConnector();
var fields = cc.getFields();
var types = cc.FieldType;
var aggregations = cc.AggregationType;
fields.newDimension()
.setId('packageName')
.setType(types.TEXT);
fields.newMetric()
.setId('downloads')
.setType(types.NUMBER)
.setAggregation(aggregations.SUM);
fields.newDimension()
.setId('day')
.setType(types.YEAR_MONTH_DAY);
return fields;
}
function getSchema(request) {
var fields = getFields(request).build();
return { schema: fields };
}
Na podstawie tego schematu możesz oczekiwać, że na ekranie pól Studia danych zobaczysz te pola, gdy użyjesz łącznika w Studio danych. Więcej informacji na ten temat znajdziesz w dalszej części artykułu, gdy będziesz testować oprogramowanie sprzęgające.
Przejdźmy do naszej ostatniej funkcji – getData().
9. Definiowanie funkcji getData() : część 1
Studio danych wywołuje funkcję getData() za każdym razem, gdy musi pobrać dane. Na podstawie odpowiedzi podanej przez getData() Studio danych będzie renderować i aktualizować wykresy w panelu. Funkcja getData() może być wywoływana w tych przypadkach:
- Użytkownik dodaje wykres do panelu
- Użytkownik edytuje wykres
- Użytkownik wyświetla panel
- Użytkownik edytuje filtr lub powiązane ustawienie danych
- Studio danych potrzebuje próbki danych
Nie musisz kopiować żadnego kodu z tej strony, ponieważ skopiujesz gotowy
getData()
w kolejnym kroku.
Obiekt request
Studio danych przekazuje obiekt request z każdym wywołaniem getData(). Sprawdź strukturę obiektu request poniżej. Pomoże Ci to napisać kod funkcji getData().
Struktura obiektu request
{
configParams: object,
scriptParams: object,
dateRange: {
startDate: string,
endDate: string
},
fields: [
{
name: Field.name
}
]
}
- Obiekt
configParamsbędzie zawierać wartości konfiguracji parametrów zdefiniowanych wgetConfig()i skonfigurowanych przez użytkownika. - Obiekt
scriptParamsbędzie zawierać informacje związane z wykonaniem łącznika. W tym ćwiczeniu nie musisz z niego korzystać. dateRangebędzie zawierać żądany zakres dat, jeśli został on uwzględniony w odpowiedzigetConfig().fieldsbędzie zawierać listę nazw pól, dla których są wymagane dane.
W przypadku łącznika przykład funkcji requestgetData() może wyglądać tak:
{
configParams: {
package: 'jquery'
},
dateRange: {
startDate: '2017-07-16',
endDate: '2017-07-18'
},
fields: [
{
name: 'day',
},
{
name: 'downloads',
}
]
}
W przypadku wywołania getData() w powyższym request żądane są tylko 2 pola, mimo że schemat złącza zawiera dodatkowe pola. Na następnej stronie znajdziesz przykładową odpowiedź na to wywołanie getData() i ogólną strukturę odpowiedzi getData().
10. Definiowanie funkcji getData() – część 2
W getData()odpowiedzigetData() musisz podać zarówno schemat, jak i dane w przypadku żądanych pól. Kod podzielisz na 3 segmenty:
- Utwórz schemat dla żądanych pól.
- Pobieranie i parsowanie danych z interfejsu API.
- przekształcanie przeanalizowanych danych i filtrowanie ich pod kątem żądanych pól;
Nie musisz kopiować żadnego kodu z tej strony, ponieważ skopiujesz gotowy
getData()
kod na następnej stronie.
To struktura getData() dla Twojego oprogramowania sprzęgającego.
function getData(request) {
// TODO: Create schema for requested fields.
// TODO: Fetch and parse data from API.
// TODO: Transform parsed data and filter for requested fields.
return {
schema: <filtered schema>,
rows: <transformed and filtered data>
};
}
Tworzenie schematu dla żądanych pól
// Create schema for requested fields
var requestedFieldIds = request.fields.map(function(field) {
return field.name;
});
var requestedFields = getFields().forIds(requestedFieldIds);
Pobieranie i parsowanie danych z interfejsu API
Adres URL interfejsu npm API będzie miał ten format:
https://api.npmjs.org/downloads/point/{start_date}:{end_date}/{package}
Utwórz adres URL interfejsu API, używając wartości request.dateRange.startDate, request.dateRange.endDate i request.configParams.package podanych przez Studio danych. Następnie pobierz dane z interfejsu API za pomocą funkcji UrlFetchApp(klasa Apps Script: reference). Potem przeanalizuj pobraną odpowiedź.
// Fetch and parse data from API
var url = [
'https://api.npmjs.org/downloads/range/',
request.dateRange.startDate,
':',
request.dateRange.endDate,
'/',
request.configParams.package
];
var response = UrlFetchApp.fetch(url.join(''));
var parsedResponse = JSON.parse(response).downloads;
Przekształcanie przeanalizowanych danych i filtrowanie ich pod kątem żądanych pól
Odpowiedź z interfejsu npm API będzie miała następujący format:
{
downloads: [
{
day: '2014-02-27',
downloads: 1904088
},
..
{
day: '2014-03-04',
downloads: 7904294
}
],
start: '2014-02-25',
end: '2014-03-04',
package: 'somepackage'
}
Przekształć odpowiedź z interfejsu npm API i podaj getData() w tym formacie: Jeśli ten format jest niejasny, zapoznaj się z przykładową odpowiedzią w następnym akapicie.
{
schema: [
{
object(Field)
}
],
rows: [
{
values: [string]
}
]
}
W odpowiedzi zwróć schemat tylko dla żądanych pól, używając właściwości schema. Dane zwrócisz za pomocą właściwości rows w postaci listy wierszy. W przypadku każdego wiersza kolejność pól w values musi być zgodna z kolejnością pól w schema. Na podstawie wcześniejszego przykładu request odpowiedź dla getData() będzie wyglądać tak:
{
schema: requestedFields.build(),
rows: [
{
values: [ 38949, '20170716']
},
{
values: [ 165314, '20170717']
},
{
values: [ 180124, '20170718']
},
]
}
Podzbiór schematu został już utworzony. Użyj tej funkcji, aby przekształcić przeanalizowane dane i odfiltrować je pod kątem żądanych pól.
function responseToRows(requestedFields, response, packageName) {
// Transform parsed data and filter for requested fields
return response.map(function(dailyDownload) {
var row = [];
requestedFields.asArray().forEach(function (field) {
switch (field.getId()) {
case 'day':
return row.push(dailyDownload.day.replace(/-/g, ''));
case 'downloads':
return row.push(dailyDownload.downloads);
case 'packageName':
return row.push(packageName);
default:
return row.push('');
}
});
return { values: row };
});
}
11. Definiowanie funkcji getData() : część 3
Połączony kod getData() będzie wyglądać jak ten poniżej. Dodaj do pliku Code.gs ten kod:
Code.gs
function responseToRows(requestedFields, response, packageName) {
// Transform parsed data and filter for requested fields
return response.map(function(dailyDownload) {
var row = [];
requestedFields.asArray().forEach(function (field) {
switch (field.getId()) {
case 'day':
return row.push(dailyDownload.day.replace(/-/g, ''));
case 'downloads':
return row.push(dailyDownload.downloads);
case 'packageName':
return row.push(packageName);
default:
return row.push('');
}
});
return { values: row };
});
}
function getData(request) {
var requestedFieldIds = request.fields.map(function(field) {
return field.name;
});
var requestedFields = getFields().forIds(requestedFieldIds);
// Fetch and parse data from API
var url = [
'https://api.npmjs.org/downloads/range/',
request.dateRange.startDate,
':',
request.dateRange.endDate,
'/',
request.configParams.package
];
var response = UrlFetchApp.fetch(url.join(''));
var parsedResponse = JSON.parse(response).downloads;
var rows = responseToRows(requestedFields, parsedResponse, request.configParams.package);
return {
schema: requestedFields.build(),
rows: rows
};
}
Plik Code.gs jest gotowy. Następnie zaktualizuj plik manifestu.
12. Aktualizowanie pliku manifestu
W edytorze skryptów Apps Script kliknij Ustawienia projektu > Wyświetlaj plik manifestu „appsscript.json” w edytorze.
Spowoduje to utworzenie nowego pliku manifestu appsscript.json.
Zastąp plik appscript.json tym kodem:
appsscript.json
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"dataStudio": {
"name": "npm Downloads - From Codelab",
"logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20logo/npm-logo-red.png",
"company": "Codelab user",
"companyUrl": "https://developers.google.com/looker-studio/",
"addonUrl": "https://github.com/googledatastudio/example-connectors/tree/master/npm-downloads",
"supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
"description": "Get npm package download counts.",
"sources": ["npm"]
}
}
Zapisz projekt Apps Script.
Gratulacje! Pierwsze społecznościowe oprogramowanie sprzęgające zostało utworzone i jest gotowe do testowania.
13. Testowanie oprogramowania sprzęgającego w Studiu danych
Korzystanie z wdrożenia
Krok 1. W środowisku programistycznym Apps Script kliknij Wdróż > Testowe wdrożenia, aby otworzyć okno Testowe wdrożenia.
Wyświetlone zostanie domyślne wdrożenie Wdrożenie główne.
Krok 2. Kliknij Kopiuj, aby skopiować identyfikator wdrożenia nagłówka.
Krok 3. Aby wczytać łącznik w Studiu danych, zastąp w tym linku symbol zastępczy <HEAD_DEPLOYMENT_ID> identyfikatorem wdrożenia głównego łącznika i kliknij link w przeglądarce:
https://lookerstudio.google.com/datasources/create?connectorId=<HEAD_DEPLOYMENT_ID>
Autoryzowanie oprogramowania sprzęgającego
Użytkownicy, którzy korzystają ze Studia danych po raz pierwszy: jeśli nie używasz jeszcze Studia danych, pojawi się prośba o przyznanie mu uprawnień i zaakceptowanie warunków. Przeprowadź proces autoryzacji. Podczas pierwszego użycia Studia danych może się też pojawić okno z prośbą o zaktualizowanie preferencji marketingowych. Jeśli chcesz otrzymywać e-maile z informacjami o najnowszych funkcjach, aktualizacjach i nowościach, zarejestruj się, aby otrzymywać ogłoszenia o usługach.
Po wczytaniu pojawi się prośba o autoryzację łącznika.
Kliknij Autoryzuj i przyznaj oprogramowaniu sprzęgającemu wymagane uprawnienia.
Konfigurowanie oprogramowania sprzęgającego
Po zakończeniu autoryzacji pojawi się ekran konfiguracji. Wpisz „lighthouse” w obszarze wprowadzania tekstu i w prawym górnym rogu kliknij Połącz.
Potwierdź schemat
Zobaczysz ekran pól. W prawym górnym rogu kliknij Utwórz raport.
Tworzenie panelu informacyjnego
Znajdziesz się w środowisku panelu Studia danych. Kliknij Dodaj do raportu.
W Studiu danych za każdym razem, gdy użytkownik uzyskuje dostęp do łącznika i dodaje nową konfigurację, na jego koncie w Studiu danych tworzone jest nowe źródło danych. Źródło danych to instancja łącznika utworzona na podstawie określonej konfiguracji. Na podstawie wybranego przez użytkownika oprogramowania sprzęgającego i konfiguracji źródło danych zwróci tabelę danych z określonym zestawem pól. Użytkownicy mogą tworzyć wiele źródeł danych z tego samego łącznika. Źródło danych może być używane w wielu raportach, a ten sam raport może korzystać z wielu źródeł danych.
Teraz dodaj wykres szeregów czasowych. W menu kliknij Wstaw > Szereg czasowy. Następnie umieść szereg czasowy na obszarze roboczym. Powinien pojawić się wykres szeregów czasowych liczby pobrań pakietu npm dla wybranego pakietu. Dodaj kontrolkę filtra dat i wyświetl panel, jak pokazano poniżej.
To wszystko. Właśnie udało Ci się utworzyć pierwsze społecznościowe oprogramowanie sprzęgające. To już koniec tego ćwiczenia. Zobaczmy teraz, jakie dalsze kroki możesz podjąć.
14. Dalsze kroki
Ulepszanie utworzonego łącznika
Wprowadź ulepszenia do utworzonego właśnie łącznika:
- Jeśli w Data Studio nie podasz nazwy pakietu na ekranie konfiguracji oprogramowania sprzęgającego, podczas rysowania wykresu szeregów czasowych zobaczysz komunikat o błędzie. Spróbuj dodać do konfiguracji oprogramowania sprzęgającego weryfikację danych wejściowych lub opcję domyślną.
- Spróbuj dodać do konfiguracji oprogramowania sprzęgającego obsługę zapytań dotyczących wielu nazw pakietów jednocześnie. Wskazówka: interfejs API liczby pobrań pakietu npm obsługuje wprowadzanie wielu nazw pakietów oddzielonych przecinkami.
- Rozwiązania obu tych problemów znajdziesz w kodzie złącza npm.
Więcej możliwości dzięki złączom społeczności
- Wyświetl dokumentację interfejsu API łącznika i pliku manifestu.
- Aby poznać sprawdzone metody, zapoznaj się z przykładowym kodem oprogramowania sprzęgającego w naszym repozytorium open source.
- Wykonaj ćwiczenie programistyczne clasp, aby móc tworzyć złącza społecznościowe w środowisku lokalnym.
- Po utworzeniu kompletnego złącza społeczności zapoznaj się z dostępnymi opcjami publikowania.
- Tworzenie wizualizacji utworzonej przez społeczność w Studiu danych.
Dodatkowe materiały
Poniżej znajdziesz różne materiały, które pomogą Ci lepiej poznać tematy poruszane w tym module.
Typ zasobu | Funkcje dla użytkowników | Funkcje dla programistów | |
Dokumentacja | |||
Wiadomości i aktualności | Zarejestruj się w Studio danych > Ustawienia użytkownika. | ||
Zadawanie pytań | |||
Filmy | |||
Przykłady | |||