Memuat data ServiceNow ke BigQuery

Anda dapat memuat data dari ServiceNow ke BigQuery menggunakan konektor BigQuery Data Transfer Service untuk ServiceNow. Dengan BigQuery Data Transfer Service, Anda dapat menjadwalkan tugas transfer berulang yang menambahkan data terbaru dari ServiceNow ke BigQuery.

Batasan

Transfer data ServiceNow tunduk pada batasan berikut:

• Konektor ServiceNow hanya mendukung ServiceNow Table API.
• Sebaiknya jangan jalankan transfer data serentak pada instance ServiceNow yang sama. Hal ini dapat menyebabkan penundaan atau kegagalan karena beban pada instance ServiceNow.
  • Sebaiknya atur waktu mulai transfer Anda secara terpisah untuk mencegah transfer berjalan secara bersamaan.
• Untuk meningkatkan performa transfer data, sebaiknya batasi jumlah aset hingga 20 item per transfer data.
• Waktu interval minimum antar-transfer data berulang adalah 15 menit. Interval default untuk transfer berulang adalah 24 jam.
• Satu konfigurasi transfer hanya dapat mendukung satu kali menjalankan transfer data pada waktu tertentu. Jika transfer data kedua dijadwalkan untuk berjalan sebelum transfer pertama selesai, maka hanya transfer data pertama yang akan selesai, sementara transfer data lain yang tumpang-tindih dengan transfer pertama akan dilewati.
  • Untuk menghindari transfer yang dilewati dalam satu konfigurasi transfer, sebaiknya Anda memperpanjang durasi waktu antara transfer data dalam jumlah besar dengan mengonfigurasi Frekuensi pengulangan.
• Untuk menggunakan lampiran jaringan dengan transfer data ini, Anda harus membuat lampiran jaringan terlebih dahulu dengan menentukan alamat IP statis.

Batasan transfer inkremental

Transfer ServiceNow inkremental tunduk pada batasan berikut:

• Anda hanya dapat memilih DATETIME kolom sebagai kolom watermark.
• Penyerapan inkremental hanya didukung untuk aset dengan kolom watermark yang valid.
• Nilai dalam kolom tanda air harus meningkat secara monoton.
• Transfer inkremental tidak dapat menyinkronkan operasi penghapusan di tabel sumber.
• Konfigurasi transfer tunggal hanya dapat mendukung penyerapan inkremental atau penuh.
• Anda tidak dapat memperbarui objek dalam daftar asset setelah menjalankan penyerapan inkremental pertama.
• Anda tidak dapat mengubah mode penulisan dalam konfigurasi transfer setelah menjalankan penyerapan inkremental pertama.
• Anda tidak dapat mengubah kolom tanda air atau kunci utama setelah menjalankan penyerapan inkremental pertama.
• Tabel BigQuery tujuan dikelompokkan menggunakan kunci utama yang diberikan dan tunduk pada batasan tabel berklaster.
• Saat Anda memperbarui konfigurasi transfer yang ada ke mode penyerapan inkremental untuk pertama kalinya, transfer data pertama setelah pembaruan tersebut akan mentransfer semua data yang tersedia dari sumber data Anda. Setiap transfer data inkremental berikutnya hanya akan mentransfer baris baru dan yang diperbarui dari sumber data Anda.

Opsi penyerapan data

Bagian ini menjelaskan opsi penyerapan data untuk menyiapkan transfer data ServiceNow.

Transfer penuh atau inkremental

Anda menentukan cara data dimuat ke BigQuery dengan memilih preferensi tulis Penuh atau Bertahap dalam konfigurasi transfer saat Anda menyiapkan transfer ServiceNow. Transfer inkremental didukung dalam pratinjau.

Catatan: Untuk meminta masukan atau dukungan terkait transfer inkremental, kirim email ke [e-mail].

Anda dapat mengonfigurasi transfer data penuh untuk mentransfer semua data dari kumpulan data ServiceNow Anda dengan setiap transfer data.

Atau, Anda dapat mengonfigurasi transfer data inkremental (Pratinjau) untuk hanya mentransfer data yang berubah sejak transfer data terakhir, bukan memuat seluruh set data dengan setiap transfer data. Jika memilih Bertahap untuk transfer data, Anda harus menentukan mode penulisan Tambahkan atau Gabungkan untuk menentukan cara data ditulis ke BigQuery selama transfer data bertahap. Bagian berikut menjelaskan mode penulisan yang tersedia.

Mode penulisan upsert

Mode penulisan upsert memperbarui baris atau menyisipkan baris baru di tabel tujuan dengan memeriksa kunci utama. Anda dapat menentukan kunci utama agar konektor ServiceNow dapat menentukan perubahan yang diperlukan untuk terus memperbarui tabel tujuan dengan tabel sumber. Jika kunci primer yang ditentukan ada di tabel BigQuery tujuan selama transfer data, konektor ServiceNow akan memperbarui baris tersebut dengan data baru dari tabel sumber. Jika kunci utama tidak ada selama transfer data, konektor ServiceNow akan menyisipkan baris baru.

Saat memilih mode upsert, Anda harus memilih kolom tanda air dan kunci utama:

• Kolom tanda air diperlukan agar konektor ServiceNow dapat melacak perubahan dalam tabel sumber.

  Pilih kolom tanda air yang diperbarui setiap kali baris diubah. Kami merekomendasikan kolom yang mirip dengan kolom UPDATED_AT atau LAST_MODIFIED.

• Kunci utama dapat berupa satu atau beberapa kolom di tabel Anda yang diperlukan agar konektor ServiceNow dapat menentukan apakah perlu menyisipkan atau memperbarui baris.

  Pilih kolom yang berisi nilai non-null yang unik di semua baris tabel. Sebaiknya gunakan kolom yang menyertakan ID yang dibuat sistem, kode referensi unik (misalnya, ID yang bertambah otomatis), atau ID urutan berbasis waktu yang tidak dapat diubah.

  Untuk mencegah kemungkinan hilangnya data atau kerusakan data, kolom kunci utama yang Anda pilih harus memiliki nilai unik. Jika Anda meragukan keunikan kolom kunci utama yang Anda pilih, sebaiknya gunakan penyerapan penuh.

Perilaku penyerapan inkremental

Saat Anda membuat perubahan pada skema tabel di sumber data, transfer data inkremental dari tabel tersebut akan tercermin di BigQuery dengan cara berikut:

Perubahan pada sumber data	Perilaku penyerapan inkremental
Menambahkan kolom baru	Kolom baru ditambahkan ke tabel BigQuery tujuan. Semua data sebelumnya untuk kolom ini akan memiliki nilai null.
Menghapus kolom	Kolom yang dihapus tetap ada di tabel BigQuery tujuan. Entri baru ke kolom yang dihapus ini diisi dengan nilai null.
Mengubah jenis data dalam kolom	Konektor hanya mendukung konversi jenis data yang didukung oleh pernyataan DDL ALTER COLUMN. Konversi jenis data lainnya akan menyebabkan transfer data gagal. Jika Anda mengalami masalah, sebaiknya buat konfigurasi transfer baru.
Mengganti nama kolom	Kolom asli tetap ada di tabel BigQuery tujuan seperti apa adanya, sementara kolom baru ditambahkan ke tabel tujuan dengan nama yang diperbarui.

Sebelum memulai

Sebelum membuat transfer data ServiceNow, lakukan hal berikut untuk ServiceNow dan BigQuery.

Prasyarat ServiceNow

• Untuk mengakses ServiceNow API, buat kredensial OAuth.

• Semua aplikasi ServiceNow berikut harus diaktifkan di instance ServiceNow:

  • Pengadaan
  • Katalog Produk
  • Pengelolaan Kontrak

• Untuk memulai transfer ServiceNow, Anda harus memiliki kredensial yang benar untuk terhubung ke instance ServiceNow.

  • Untuk mendapatkan kredensial ke instance developer ServiceNow, login ke portal developer ServiceNow. Anda dapat menggunakan nama pengguna dan sandi yang tercantum di halaman Kelola sandi instance. Untuk informasi tentang cara mereset sandi ServiceNow Anda, lihat Password Reset
  • Untuk mendapatkan kredensial ke instance produksi atau sub-produksi ServiceNow, hubungi administrator pelanggan ServiceNow Anda untuk meminta nama pengguna dan sandi.

Prasyarat BigQuery

• Selesaikan semua tindakan yang diperlukan untuk mengaktifkan BigQuery Data Transfer Service.
• Buat set data BigQuery untuk menyimpan data.
• Jika ingin menyiapkan notifikasi operasi transfer untuk Pub/Sub, pastikan Anda memiliki izin Identity and Access Management (IAM) pubsub.topics.setIamPolicy. Jika Anda hanya menyiapkan notifikasi email, izin Pub/Sub tidak diperlukan. Untuk mengetahui informasi selengkapnya, lihat Notifikasi operasi BigQuery Data Transfer Service.

Peran BigQuery yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat transfer data BigQuery Data Transfer Service, minta administrator untuk memberi Anda peran IAM BigQuery Admin (roles/bigquery.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat transfer data BigQuery Data Transfer Service. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat transfer data BigQuery Data Transfer Service:

• Izin BigQuery Data Transfer Service:
  • bigquery.transfers.update
  • bigquery.transfers.get
• Izin BigQuery:
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
  • bigquery.jobs.create

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Untuk mengetahui informasi selengkapnya, lihat Memberikan akses bigquery.admin.

Menyiapkan transfer data ServiceNow

Tambahkan data ServiceNow ke BigQuery dengan menyiapkan konfigurasi transfer menggunakan salah satu opsi berikut:

Konsol

1. Buka halaman Transfer data di konsol Google Cloud .

   Buka Data transfers

2. Klik Create transfer.

3. Di bagian Source type, untuk Source, pilih ServiceNow.

4. Di bagian Detail sumber data, lakukan hal berikut:

   • (Opsional) Untuk Network attachment, pilih network attachment dari menu drop-down, atau klik Create Network Attachment.
     • Pilih lampiran jaringan untuk mengonfigurasi transfer data ini agar menggunakan satu alamat IP yang konsisten. Anda dapat menggunakan opsi ini jika instance ServiceNow Anda dikonfigurasi untuk hanya menerima traffic dari alamat IP tertentu.
     • Untuk mengetahui informasi selengkapnya tentang cara membuat lampiran jaringan, lihat Mengonfigurasi koneksi dengan lampiran jaringan
     • Untuk mengetahui informasi selengkapnya tentang cara menentukan alamat IP di ServiceNow, lihat Menentukan alamat IP internal ServiceNow yang diizinkan
   • Untuk Instance ID, masukkan ID instance ServiceNow. Anda bisa mendapatkannya dari URL ServiceNow Anda—misalnya, https://INSTANCE_ID.service-now.com.
   • (Opsional) Untuk ServiceNow Cloud Type, pilih jenis cloud untuk akun ServiceNow Anda:
     • Pilih Komersial jika URL instance ServiceNow Anda mengikuti pola https://INSTANCE_ID.service-now.com. Ini adalah nilai defaultnya.
     • Pilih Government Community Cloud (GCC) jika URL instance ServiceNow Anda mengikuti pola https://INSTANCE_ID.servicenowservices.com.
   • Untuk Username, masukkan nama pengguna ServiceNow yang akan digunakan untuk koneksi.
   • Untuk Password, masukkan sandi ServiceNow.
   • Untuk Client ID, masukkan client ID dari kredensial OAuth Anda. Untuk membuat kredensial, lihat Membuat Kredensial OAuth.
   • Untuk Client secret, masukkan rahasia klien dari kredensial OAuth Anda.
   • Untuk Enable legacy mapping, pilih true (default) untuk menggunakan pemetaan jenis data lama. Pilih false untuk menggunakan pemetaan jenis data yang diperbarui. Untuk mengetahui informasi selengkapnya tentang pembaruan pemetaan jenis data, lihat 16 Maret 2027.
   • Untuk Ingestion type, pilih Full atau Incremental.
     • Jika Anda memilih Incremental (Pratinjau), untuk Write mode, pilih Upsert. Untuk mengetahui informasi selengkapnya tentang mode penulisan, lihat Transfer penuh atau inkremental.
   • Untuk Tabel ServiceNow yang akan ditransfer, klik Jelajahi:
     • Pilih objek yang akan ditransfer ke set data tujuan BigQuery. Anda juga dapat memasukkan objek secara manual untuk disertakan dalam transfer data di kolom ini.
     • Jika Anda telah memilih Upsert sebagai mode penulisan inkremental, Anda harus memilih kolom sebagai kolom tanda air, lalu memilih satu atau beberapa kolom sebagai kunci utama.
   • Untuk Jenis nilai, pilih salah satu opsi berikut:
     • Untuk mentransfer nilai yang disimpan dalam database, pilih Aktual.
     • Untuk mentransfer nilai tampilan kolom, pilih Tampilan.

5. Di bagian Destination settings, untuk Dataset, pilih set data yang Anda buat untuk menyimpan data Anda.

6. Di bagian Transfer config name, untuk Display name, masukkan nama untuk transfer data.

7. Di bagian Opsi jadwal, lakukan tindakan berikut:

   • Dalam daftar Frekuensi pengulangan, pilih opsi untuk menentukan seberapa sering transfer data ini dijalankan. Untuk menentukan frekuensi pengulangan kustom, pilih Kustom. Jika Anda memilih On-demand, transfer data ini akan berjalan saat Anda memicu transfer secara manual.
   • Jika berlaku, pilih Start now atau Start at set time, lalu masukkan tanggal mulai dan waktu proses.

8. Opsional: Di bagian Opsi notifikasi, lakukan hal berikut:

   • Untuk mengaktifkan notifikasi email, klik tombol Notifikasi email. Saat Anda mengaktifkan opsi ini, administrator transfer akan menerima notifikasi email saat proses transfer gagal.
   • Untuk mengaktifkan notifikasi operasi transfer Pub/Sub untuk transfer data ini, klik tombol Notifikasi Pub/Sub. Anda dapat memilih nama topik, atau Anda dapat mengklik Buat topik untuk membuatnya.

9. Klik Simpan.

bq

Masukkan perintah bq mk dan berikan flag pembuatan transfer, --transfer_config:

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=DISPLAY_NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Ganti kode berikut:

• PROJECT_ID (opsional): Project ID Google Cloud Anda. Jika project ID tidak ditentukan, project default akan digunakan.
• DATA_SOURCE: sumber data (misalnya, servicenow).
• DISPLAY_NAME: nama tampilan untuk konfigurasi transfer. Nama transfer data dapat berupa nilai apa pun yang memungkinkan Anda mengidentifikasi transfer jika perlu mengubahnya nanti.
• DATASET: set data target untuk konfigurasi transfer.

• PARAMETERS: parameter untuk konfigurasi transfer yang dibuat dalam format JSON. Contoh: --params='{"param":"param_value"}'. Berikut adalah parameter untuk transfer data ServiceNow:

  Parameter ServiceNow	Wajib diisi atau opsional	Deskripsi
  connector.networkAttachment	Opsional	Nama Lampiran jaringan yang akan digunakan untuk memastikan konektivitas ke Instance ServiceNow.
  connector.instanceId	Wajib	ID instance dari instance ServiceNow
  connector.authentication.username	Wajib	Nama pengguna untuk instance ServiceNow pengguna.
  connector.authentication.password	Wajib	Sandi untuk instance ServiceNow pengguna.
  connector.authentication.oauth.clientId	Wajib	Client ID untuk autentikasi OAuth dengan instance ServiceNow.
  connector.authentication.oauth.clientSecret	Wajib	Rahasia Klien untuk autentikasi OAuth dengan instance ServiceNow.
  connector.instanceCloudType	Opsional	Tentukan jenis cloud akun ServiceNow Anda. Nilai yang didukung adalah: COMMERCIAL_CLOUD, jika URL instance ServiceNow Anda mengikuti pola https://INSTANCE_ID.service-now.com GOVERNMENT_COMMUNITY_CLOUD jika URL instance ServiceNow Anda mengikuti pola https://INSTANCE_ID.servicenowservices.com
  ingestionType	Opsional	Menentukan metode untuk mentransfer data dari ServiceNow sumber ke tujuan, menentukan apakah pemuatan ulang set data lengkap atau update inkremental yang efisien dilakukan.
  writeMode	Opsional	Jika menggunakan penyerapan inkremental, tentukan strategi sinkronisasi untuk penyerapan inkremental. Kolom ini wajib diisi untuk transfer inkremental. Nilai yang didukung adalah WRITE_MODE_UPSERT.
  assets	Wajib	Daftar nama tabel ServiceNow yang akan ditransfer dari ServiceNow sebagai bagian dari transfer.
  watermarkColumns	Opsional	Jika menggunakan penyerapan inkremental, kolom tabel sumber (biasanya datetime) yang digunakan untuk melacak titik sinkronisasi terakhir yang berhasil, sehingga konektor dapat membuat kueri dan mentransfer hanya data yang telah dibuat atau diubah sejak waktu tertentu tersebut secara efisien. Kolom ini wajib diisi untuk transfer inkremental.
  primaryKeys	Opsional	Jika menggunakan penyerapan inkremental, kolom unik atau kombinasi kolom yang digunakan untuk mengidentifikasi setiap baris dalam tabel sumber secara unik. Kolom ini wajib diisi untuk transfer inkremental.
  valueType	Opsional	Mengontrol cara jenis data tertentu dari ServiceNow dipetakan ke jenis data BigQuery.
  connector.legacyMapping	Wajib	Tetapkan ke true (default) untuk menggunakan pemetaan jenis data lama. Tetapkan ke false untuk menggunakan pemetaan jenis data yang diperbarui. Jika Anda melakukan transfer inkremental, nilai ini harus false. Untuk mengetahui informasi selengkapnya tentang pembaruan pemetaan jenis data, lihat 16 Maret 2027.

  Saat menentukan beberapa aset selama transfer inkremental, nilai kolom watermarkColumns dan primaryKeys sesuai dengan posisi nilai di kolom assets. Pastikan urutan tabel dan kolomnya dipertahankan secara konsisten di semua daftar konfigurasi terkait.

  Misalnya, perintah berikut akan membuat transfer data ServiceNow di project default dengan semua parameter yang diperlukan:

    bq mk
      --transfer_config
      --target_dataset=mydataset
      --data_source=servicenow
      --display_name='My Transfer'
      --params='{"connector.authentication.oauth.clientId": "1234567890",
          "connector.authentication.oauth.clientSecret":"ABC12345",
          "connector.authentication.username":"user1",
          "connector.authentication.password":"abcdef1234",
          "connector.instanceId":"dev-instance",
          "connector.networkAttachment": "projects/dev-project1/regions/us-central1/networkattachments/na1"}'
  

  Perintah berikut akan membuat transfer data ServiceNow inkremental di project default, dan menggunakan mode penulisan UPSERT.

    bq mk
        --transfer_config
        --target_dataset=mydataset
        --data_source=servicenow
        --display_name='My Transfer'
        --params='{"assets": ["incident", "change_request"],
            "connector.authentication.oauth.clientId": "1234567890",
            "connector.authentication.oauth.clientSecret":"ABC12345",
            "connector.authentication.username":"user1",
            "connector.authentication.password":"abcdef1234",
            "connector.instanceId":"dev-instance",
            "ingestionType":"incremental",
            "writeMode":"WRITE_MODE_UPSERT",
            "watermarkColumns":["sys_updated_on","sys_updated_on"],
            "primaryKeys":[["sys_id"], ["sys_id"]]}'
  

API

Gunakan metode projects.locations.transferConfigs.create dan berikan instance resource TransferConfig.

Saat Anda menyimpan konfigurasi transfer, konektor ServiceNow akan otomatis memicu proses transfer sesuai dengan opsi jadwal Anda. Dengan setiap operasi transfer, konektor ServiceNow mentransfer semua data yang tersedia dari ServiceNow ke BigQuery.

Untuk menjalankan transfer data secara manual di luar jadwal rutin, Anda dapat memulai operasi pengisian ulang.

Pemetaan jenis data

Catatan: Pada 16 Maret 2027, konektor ServiceNow akan memperbarui beberapa pemetaan jenis datanya. Untuk mengetahui informasi selengkapnya, lihat 16 Maret 2027.

Tabel berikut menunjukkan cara jenis data dipetakan dalam transfer data ServiceNow:

Jenis data ServiceNow	Jenis data BigQuery	Jenis data BigQuery yang diperbarui
decimal	FLOAT64
integer	INTEGER
boolean	BOOLEAN
glide_date	DATE
glide_date_time	DATETIME
glide_list	STRING	ARRAY
glide_time	INT64
reference	STRING
currency	STRING
sys_class_name	STRING
domain_id	STRING
domain_path	STRING
guid	STRING
translated_html	STRING
journal	STRING
string	STRING
list	STRING	ARRAY

Memecahkan masalah transfer

Bagian berikut menjelaskan masalah umum saat menyiapkan transfer data ServiceNow.

Untuk mengetahui informasi selengkapnya, lihat Memecahkan masalah konfigurasi transfer.

Transfer gagal karena pengaktifan ServiceNow

Masalah terjadi yang menyebabkan transfer data gagal saat aplikasi Pengadaan, Katalog Produk, atau Pengelolaan Kontrak tidak diaktifkan di ServiceNow. Untuk memperbaikinya, aktifkan ketiga aplikasi:

• Pengadaan
• Katalog Produk
• Pengelolaan Kontrak (diaktifkan secara default)

Masalah terjadi selama menjalankan transfer

Terjadi masalah yang menyebabkan operasi transfer tidak dibuat seperti yang diinginkan. Untuk mengatasi masalah ini, lakukan langkah berikut:

• Periksa apakah kredensial akun ServiceNow, seperti nilai Nama pengguna, Sandi, ID klien, dan Rahasia klien, valid.
• Pastikan bahwa ID Instance adalah ID valid dari instance ServiceNow Anda.

Error lainnya

Untuk mengetahui informasi tentang error lain yang terjadi selama transfer data ServiceNow, lihat Masalah transfer ServiceNow

Harga

Untuk mengetahui informasi harga tentang transfer ServiceNow, lihat Harga Data Transfer Service.

Langkah berikutnya

• Untuk ringkasan BigQuery Data Transfer Service, lihat Pengantar BigQuery Data Transfer Service.
• Untuk informasi cara menggunakan transfer, termasuk mendapatkan informasi tentang konfigurasi transfer, membuat listingan konfigurasi transfer, dan melihat histori pelaksanaan transfer, lihat Menangani transfer.
• Pelajari cara memuat data dengan operasi lintas-cloud.