Kueri alur data menggunakan DataWorks OpenAPI - DataWorks

Dokumen ini menjelaskan cara menggunakan DataWorks OpenAPI (2024-05-18) untuk mengkueri alur data tabel dan bidang secara terprogram. Dokumen ini menyediakan contoh pemanggilan API dan kode SDK spesifik guna membantu Anda memulai dengan cepat serta melakukan analisis alur data secara otomatis dan batch.

Apa itu alur data?

Bayangkan Anda sedang melihat laporan bisnis penting yang menunjukkan peningkatan signifikan dalam penjualan kuartal ini. Sebagai analis atau manajer data yang teliti, beberapa pertanyaan akan muncul di benak Anda:

Bagaimana metrik "penjualan" ini dihitung?
Apa sumber data bisnisnya? Apakah berasal dari tabel pesanan atau tabel transaksi pembayaran?
Langkah-langkah pemrosesan apa saja yang dilalui data tersebut dari sumber hingga laporan akhir, seperti pembersihan, transformasi, dan agregasi?
Jika terdapat kesalahan pada data metrik ini, laporan atau aplikasi hilir mana saja yang akan terpengaruh?

Alur data yang jelas sangat penting karena memberikan manfaat inti berikut:

Pelacakan data dan troubleshooting
Saat Anda menemukan anomali atau kesalahan data, Anda dapat melacak alur data ke hulu untuk segera mengidentifikasi langkah pemrosesan atau data sumber yang menyebabkan masalah tersebut. Hal ini secara signifikan mengurangi waktu troubleshooting.
Analisis dampak
Saat Anda perlu mengubah skema tabel, bidang, atau logika perhitungan, Anda dapat menganalisis alur data ke hilir untuk menilai secara akurat data dan laporan bisnis hilir mana saja yang akan terpengaruh. Pendekatan ini membantu Anda menghindari risiko tak terduga akibat satu perubahan yang berpotensi menyebabkan masalah luas.
Tata kelola data dan kredibilitas
Alur data yang jelas merupakan fondasi bagi manajemen aset data, penerapan standar data, dan pemantauan Kualitas Data. Alur data membuat seluruh siklus hidup data menjadi transparan dan meningkatkan kepercayaan pengguna bisnis terhadap data.
Optimasi biaya dan inventaris aset
Dengan menganalisis alur data, Anda dapat mengidentifikasi tabel data atau task komputasi yang tidak memiliki konsumen hilir. Informasi ini memberikan dasar untuk optimasi biaya gudang data dan pencabutan publikasi aset lama.

DataWorks secara otomatis mengurai dan mencatat alur data yang dihasilkan oleh berbagai task komputasi, seperti MaxCompute SQL dan EMR Spark. DataWorks OpenAPI memungkinkan Anda mengakses informasi alur data ini secara terprogram, sehingga Anda dapat mengintegrasikan analisis alur data ke dalam platform manajemen data Anda sendiri atau proses O&M otomatis.

Persiapan: Dapatkan ID entitas

Sebelum Anda dapat mengkueri alur data apa pun, Anda harus terlebih dahulu mendapatkan pengenal unik untuk data target (tabel atau bidang). Pengenal ini adalah entity ID. Entity ID merupakan kredensial inti untuk memanggil API terkait metadata dan alur data.

Anda dapat memperoleh entity ID dengan salah satu dari dua cara berikut:

1. Dapatkan ID dari antarmuka DataWorks

Untuk sejumlah kecil tabel atau bidang yang sudah diketahui, menyalin ID dari antarmuka merupakan metode tercepat.

Dapatkan entity ID tabel

Buka modul Data Map di DataWorks.
Cari dan buka halaman detail tabel yang ingin Anda kueri.
Di panel kiri Table Basic Information, temukan Entity ID dan salin.

Dapatkan entity ID bidang

Di halaman detail tabel, beralihlah ke tab Lineage Information dan pilih Field Lineage.
Di graf alur bidang, klik node bidang yang ingin Anda telusuri.
Panel detail bidang akan muncul di sebelah kanan. Di panel tersebut, temukan Entity ID dan salin.

2. Dapatkan ID secara batch menggunakan API

Saat Anda perlu memperoleh banyak entity ID, operasi manual menjadi tidak efisien. Dalam kasus ini, Anda dapat menggunakan OpenAPI untuk melakukan kueri batch:

Peroleh ID tabel secara batch: Panggil API ListTables. Untuk informasi selengkapnya, lihat ListTables - Kueri daftar tabel di Data Map.
Peroleh ID bidang secara batch: Panggil API ListColumns. Untuk informasi selengkapnya, lihat ListColumns - Kueri daftar bidang di tabel Data Map.

Gunakan API `ListLineages` untuk mengkueri alur data

Setelah memperoleh entity ID, Anda dapat menggunakan API inti ListLineages untuk mengkueri alur data hulu dan hilirnya.

1. Parameter API inti

Tabel berikut menjelaskan parameter permintaan utama untuk API ListLineages. Anda dapat menguji API ini secara online di OpenAPI Portal.

Parameter	Tipe	Deskripsi
`SrcEntityId`	String	Digunakan untuk mengkueri alur data hilir. Masukkan entity ID sumber (hulu). API akan mengembalikan seluruh alur data hilir untuk entitas tersebut.
`DstEntityId`	String	Digunakan untuk mengkueri alur data hulu. Masukkan entity ID tujuan (hilir). API akan mengembalikan seluruh alur data hulu untuk entitas tersebut.
`SrcEntityName`	String	Digunakan bersama `DstEntityId` untuk melakukan pencarian fuzzy dan memfilter entitas hulu.
`DstEntityName`	String	Digunakan bersama `SrcEntityId` untuk melakukan pencarian fuzzy dan memfilter entitas hilir.
`NeedAttachRelationship`	Boolean	Menentukan apakah informasi hubungan alur data yang detail disertakan dalam respons. Atur nilai ini ke `true` untuk mendapatkan konteks lengkap.

Penting

Jika Anda memberikan SrcEntityId dan DstEntityId sekaligus, API akan mengembalikan hubungan alur data antara entitas hulu dan hilir yang ditentukan.
Jika SrcEntityId dan DstEntityId sama, API akan mengembalikan hubungan alur data referensi-diri untuk entitas tersebut.

2. Contoh pemanggilan

Asumsikan Anda memiliki tabel MaxCompute dengan entity ID maxcompute-table:::test_project::test_table.

Contoh 1: Kueri alur data hilir tabel

Untuk mengkueri semua tabel hilir dari tabel ini, Anda perlu menetapkannya sebagai sumber:

SrcEntityId: maxcompute-table:::test_project::test_table
NeedAttachRelationship: true

Untuk hanya menemukan tabel hilir yang namanya mengandung "report", Anda dapat menambahkan parameter DstEntityName:

DstEntityName: report

Contoh 2: Kueri alur data hulu tabel

Untuk mengetahui tabel atau task mana yang menghasilkan tabel ini, Anda perlu menetapkannya sebagai tujuan:

DstEntityId: maxcompute-table:::test_project::test_table
NeedAttachRelationship: true

Anda juga dapat menggunakan parameter SrcEntityName untuk memfilter sumber hulu.

3. Memahami respons API

Setelah pemanggilan ListLineages berhasil, Anda akan menerima daftar hubungan alur data. Setiap hubungan mencakup entitas sumber, entitas tujuan, dan informasi asosiasinya.

Contoh respons hubungan alur data tunggal (JSON):

{
  "SrcEntity": {
    "Id": "maxcompute-table:::test_project::table_from",
    "Name": "table_from",
    "Attributes": {
      "rawEntityId": "maxcompute-table:::test_project::table_from"
    }
  },
  "DstEntity": {
    "Id": "maxcompute-table:::test_project::table_to",
    "Name": "table_to",
    "Attributes": {
      "project": "test_project",
      "region": "cn-shanghai",
      "table": "table_to"
    }
  },
  "Relationships": [
    {
      "Id": "123456789:maxcompute-table.test_project.table_from:maxcompute-table.test_project.table_to:maxcompute.SQL.76543xxx",
      "CreateTime": 1761089163548,
      "Task": {
        "Id": "76543xxx",
        "Type": "dataworks-sql",
        "Attributes": {
          "engine": "maxcompute",
          "channel": "1st",
          "taskInstanceId": "12345xxx",
          "projectId": "123456",
          "taskId": "76543xxx"
        }
      }
    }
  ]
}

Cara membaca respons:

SrcEntity dan DstEntity: Mewakili entitas hulu dan hilir dari alur data. Anda dapat memperoleh Id-nya, lalu memanggil API GetTable atau GetColumn untuk mengambil metadata lebih detail.
Relationships: Menggambarkan bagaimana SrcEntity dan DstEntity saling terkait.
- Task: Menggambarkan task yang menghasilkan hubungan alur data ini. Jika task tersebut merupakan task penjadwalan DataWorks, Task.Attributes akan berisi taskId dan taskInstanceId. Anda dapat menggunakan ID-ID ini untuk memanggil API GetTask guna memperoleh definisi detail dan status berjalan task tersebut.

Tutorial praktis Java SDK

Contoh berikut menggunakan Java SDK untuk menunjukkan proses lengkap kueri alur data.

1. Persiapkan lingkungan

Versi JDK: Pastikan Anda telah menginstal JDK 8 atau versi yang lebih baru.
Dependensi Maven: Tambahkan dependensi berikut ke file pom.xml proyek Anda. Ganti ${latest.version} dengan nomor versi SDK terbaru.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dataworks_public20240518</artifactId>
    <version>${latest.version}</version>
</dependency>

2. Contoh kode lengkap

Kode berikut menunjukkan cara menginisialisasi client, mengkueri alur data hulu dan hilir dari tabel tertentu, serta mencetak informasi penting.

import java.util.List;
import java.util.Map;

import com.aliyun.dataworks_public20240518.Client;
import com.aliyun.dataworks_public20240518.models.GetTableRequest;
import com.aliyun.dataworks_public20240518.models.GetTableResponse;
import com.aliyun.dataworks_public20240518.models.LineageEntity;
import com.aliyun.dataworks_public20240518.models.LineageRelationship;
import com.aliyun.dataworks_public20240518.models.LineageTask;
import com.aliyun.dataworks_public20240518.models.ListLineagesRequest;
import com.aliyun.dataworks_public20240518.models.ListLineagesResponse;
import com.aliyun.dataworks_public20240518.models.ListLineagesResponseBody.ListLineagesResponseBodyPagingInfo;
import com.aliyun.dataworks_public20240518.models.ListLineagesResponseBody.ListLineagesResponseBodyPagingInfoLineages;
import com.aliyun.dataworks_public20240518.models.Table;
import com.aliyun.tea.TeaException;

public class LineageQuerySample {
  /**
     * deskripsi