2022-06-09

Cara Menggunakan Plugin Meltano

Pengantar

Plugin-proyek Meltano didefinisikan dalam file proyek meltano.yml dan diinstal di dalam direktori .meltano. Plugin ini dapat dikelola menggunakan berbagai perintah CLI dan antarmuka pengguna (UI).

Menambahkan Plugin

Anda dapat menambahkan plugin dengan menjalankan perintah meltano add atau dengan langsung mengedit file meltano.yml dan kemudian menjalankan perintah meltano install.

Discoverable Plugins

Ekstraktor dan Loader yang didukung oleh Meltano (yang dapat ditemukan menggunakan meltano add) disebut sebagai "Discoverable Plugins" dalam dokumentasi resmi. Discoverable Plugins dapat ditambahkan menggunakan perintah meltano add.

bash

$ meltano add extractor tap-gitlab
$ meltano add loader target-postgres
$ meltano add transformer dbt
$ meltano add orchestrator airflow

Ketika Anda menjalankan perintah di atas, bagian plugin dalam file meltano.yml akan terlihat seperti berikut:

meltano.yml

plugins:
  extractors:
  - name: tap-gitlab
    variant: meltano
    pip_url: git+https://gitlab.com/meltano/tap-gitlab.git
  loaders:
  - name: target-postgres
    variant: datamill-co
    pip_url: singer-target-postgres
  transformer:
  - name: dbt
    pip_url: dbt
  orchestrators:
  - name: airflow
    pip_url: apache-airflow

Untuk Ekstraktor atau Loader yang sama, mungkin ada beberapa varian, yang disebut "varian" dalam dokumentasi resmi. Ketika Anda menjalankan meltano add tanpa menyebutkan varian, Meltano secara otomatis memilih varian yang direkomendasikan.

Untuk menentukan varian, gunakan perintah berikut:

bash

$ meltano add loader target-postgres --variant=transferwise

Jika Anda ingin menginstal beberapa varian, jalankan perintah seperti berikut:

bash

$ meltano add loader target-snowflake --variant=transferwise --as target-snowflake--transferwise
$ meltano add loader target-snowflake --variant=meltano --as target-snowflake--meltano

Plugin Kustom

Jika plugin yang diinginkan tidak tersedia sebagai Discoverable Plugins, Anda dapat menambahkan tap Singer atau target Singer apa pun dengan menambahkan opsi --custom ke perintah meltano add. Ikuti dokumentasi resmi untuk menambahkan Ekstraktor yang tidak ada dalam Discoverable Plugins.

bash

$ meltano add --custom extractor tap-covid-19

Ketika Anda menjalankan perintah di atas, Anda akan diminta dengan pertanyaan interaktif.

Adding new custom extractor with name 'tap-covid-19'...

Specify the plugin's namespace, which will serve as the:
- identifier to find related/compatible plugins
- default database schema (`load_schema` extra),
  for use by loaders that support a target schema

Hit Return to accept the default: plugin name with underscores instead of dashes

(namespace) [tap_covid_19]: tap_covid_19

Specify the plugin's `pip install` argument, for example:
- PyPI package name:
	tap-covid-19
- Git repository URL:
	git+https://gitlab.com/meltano/tap-covid-19.git
- local directory, in editable/development mode:
	-e extract/tap-covid-19
- 'n' if using a local executable (nothing to install)

Default: plugin name as PyPI package name

(pip_url) [tap-covid-19]: -e extract/tap-covid-19

Specify the plugin's executable name

Default: name derived from `pip_url`

(executable) [tap-covid-19]: tap-covid-19

Specify the tap's supported Singer features (executable flags), for example:
	`catalog`: supports the `--catalog` flag
	`discover`: supports the `--discover` flag
	`properties`: supports the `--properties` flag
	`state`: supports the `--state` flag

To find out what features a tap supports, reference its documentation or try one
of the tricks under [how to test a tap](/contribute/plugins#how-to-test-a-tap).

Multiple capabilities can be separated using commas.

Default: no capabilities

(capabilities) [[]]: catalog,discover,state

Specify the tap's supported settings (`config.json` keys)

Multiple setting names (keys) can be separated using commas.

A setting kind can be specified alongside the name (key) by using the `:` delimiter,
e.g. `port:integer` to set the kind `integer` for the name `port`

Supported setting kinds:
string | integer | boolean | date_iso8601 | email | password | oauth | options | file | array | object | hidden

- Credentials and other sensitive setting types should use the password kind.
- If not specified, setting kind defaults to string.
- Nested properties can be represented using the `.` separator, e.g. `auth.username` for `{ "auth": { "username": value } }`.
- To find out what settings a tap supports, reference its documentation.

Default: no settings

(settings) [[]]: api_token:password,user_agent:string,start_date:date_iso8601
Added extractor 'tap-covid-19' to your Meltano project

Installing extractor 'tap-covid-19'...
Installed extractor 'tap-covid-19'

Bagian plugins dalam file meltano.yml akan memiliki Ekstraktor tap-covid-19 ditambahkan.

meltano.yml

plugins:
  extractors:
  - name: tap-covid-19
    namespace: tap_covid_19
    pip_url: tap-covid-19
    executable: tap-covid-19
    capabilities:
    - catalog
    - discover
    - state
    settings:
    - name: api_token
    - name: user_agent
    - name: start_date

Pewarisan Plugin

Untuk mewarisi dari Discoverable Plugins dan menginstalnya dengan nama yang berbeda, tambahkan opsi --inherit-from atau --as ke perintah.

bash

$ meltano add extractor tap-postgres--billing --inherit-from tap-postgres
$ meltano add extractor tap-postgres --as tap-postgres--billing

Bagian plugins dalam file meltano.yml akan terlihat seperti berikut:

meltano.yml

plugins:
  extractors:
  - name: tap-postgres--billing
    inherit_from: tap-postgres
    variant: transferwise
    pip_url: pipelinewise-tap-postgres

Menentukan Versi Plugin Tertentu

Jika Anda ingin menggunakan versi plugin tertentu, tentukan pip_url dalam file meltano.yml sebagai berikut:

meltano.yml

# Before:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git
pip_url: git+https://github.com/adswerve/target-bigquery.git

# After:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git@v0.9.11
pip_url: git+https://github.com/adswerve/target-bigquery.git@v0.10.2

# Alternatively:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git@2657b89e8896face4ce320a03b8413bbc196cec9
pip_url: git+https://github.com/adswerve/target-bigquery.git@3df97b951b7eebdfa331a1ff570f1fe3487d632f

Menghapus Plugin

Anda dapat menghapus plugin menggunakan perintah meltano remove.

bash

$ meltano remove extractor tap-github
$ meltano remove loader target-csv target-bigquery

Menggunakan Plugin Forked Kustom

Jika Anda ingin menggunakan repositori plugin yang difork, ubah nilai pip_url dalam bagian plugins file meltano.yml dan kemudian jalankan perintah meltano install.

meltano.yml

.
.
.
plugins:
   extractors:
   - name: tap-gitlab
     variant: meltano
     pip_url: git+https://github.com/meltano/tap-gitlab.git@ref-name #この行を修正する

bash

$ meltano install extractor tap-github

Jika repositori plugin bersifat pribadi, Anda dapat menanganinya dengan dua cara:

Menempatkan file .netrc di direktori utama

.netrc

  machine <hostname> # e.g. gitlab.com or github.com
  login <username>
  password <personal-access-token-or-password>

Otentikasi dengan SSH

  pip_url: git+ssh://git@gitlab.com/meltano/tap-gitlab.git

Mengubah Varian

Jika Anda memiliki varian yang sudah ada dan ingin beralih ke varian yang berbeda, Anda dapat menambahkan varian baru atau mengganti yang sudah ada.

Di sini, kita akan menunjukkan bagaimana mengganti varian yang sudah ada. Modifikasi bagian plugins dalam file meltano.yml sebagai berikut:

meltano.yml

- plugins:
-   loaders:
-   - name: target-postgres
-     variant: datamill-co
-     pip_url: singer-target-postgres

+ plugins:
+   loaders:
+   - name: target-postgres
+     variant: meltano
+     pip_url: git+https://github.com/meltano/target-postgres.git # Optional

Selanjutnya, jalankan perintah meltano install:

bash

$ meltano install loader target-postgres

Varian yang berbeda sering memiliki nilai konfigurasi yang berbeda. Modifikasi file meltano.yml sebagai berikut:

meltano.yml

- config:
-   postgres_host: postgres.example.com
-   postgres_port: 5432
-   postgres_username: my_user
-   postgres_database: my_database

+ config:
+   host: postgres.example.com
+   port: 5432
+   user: my_user
+   dbname: my_database

Jika Anda memiliki nilai konfigurasi lama, Anda dapat mengatur nilai baru menggunakan perintah berikut:

bash

$ meltano config target-postgres unset postgres_password
$ meltano config target-postgres set password my_password

File discovery.yml

Secara default, Meltano menambahkan plugin dengan merujuk ke file discovery.yml yang terletak di https://discovery.meltano.com/discovery.yml. Jika Anda ingin membuat plugin yang tidak ada dalam file discovery.yml ini, biasanya Anda menambahkan opsi --custom dan menjalankan perintah add untuk memasukkan konfigurasi secara interaktif. Namun, jika Anda membuat file discovery.yml sendiri, Anda dapat menghindari konfigurasi interaktif dengan menjalankan perintah export MELTANO_DISCOVERY_URL=<YOUR discovery.yml PATH>.