FAQ

​

Onboarding

​

Cara mendapatkan workbookId sebuah Spreadsheet

• Dari URL Spreadsheet: Buka Spreadsheet. ID Dokumen yang terdapat dalam URL adalah workbookId.
• Dari informasi dokumen: Di sudut kiri atas Spreadsheet, klik Menu → Spreadsheet → Informasi Dokumen. ID Dokumen yang ditampilkan di sana adalah workbookId.
• Melalui Knowledge Base API: Panggil API Get node. nodeId (dentryUuid) yang dikembalikan adalah workbookId.

​

Cara mendapatkan operatorId

1. Dapatkan userId berdasarkan nomor telepon: Panggil API Query users by phone number.
2. Dapatkan unionId berdasarkan userId: Panggil API Query user details. unionId yang dikembalikan adalah operatorId.

​

Apa yang harus dilakukan saat access token kedaluwarsa

• Simpan token beserta waktu kedaluwarsanya di cache.
• Muat ulang token secara proaktif 5 menit sebelumnya sebelum kedaluwarsa.
• Saat API mengembalikan error token tidak valid, segera muat ulang dan coba lagi.

​

Cara mengatasi error “The operator has no permission” saat memanggil API

• Apakah pengguna memiliki akses ke Spreadsheet: Pastikan pengguna telah ditambahkan sebagai Kolaborator Spreadsheet, atau Knowledge Base yang menampung Spreadsheet telah memberikan izin kepada pengguna.
• Apakah tipe izin sesuai:
  • Operasi baca seperti GetAllSheets, GetSheet, dan GetRange memerlukan izin Document.Workbook.Read.
  • Operasi tulis seperti AppendRows, UpdateRange, dan CreateSheet memerlukan izin Document.Workbook.Write.
• Apakah aplikasi telah mengajukan izin yang diperlukan: Di Kelola Aplikasi pada DingTalk Open Platform, verifikasi bahwa scope izin terkait telah diajukan dan disetujui.

​

Penggunaan API

​

Dapatkah parameter sheetId menerima nama Lembar Kerja

• Kirim ID: Sheet1, yang dibuat oleh sistem.
• Kirim nama: Sales Data, yang merupakan judul Lembar Kerja yang ditentukan pengguna.

Rekomendasi: Gunakan ID Lembar Kerja bila memungkinkan, karena nama dapat diubah oleh pengguna. Anda dapat memanggil API GetAllSheets untuk memperoleh ID dan nama semua Lembar Kerja.

​

Di mana data ditulis saat AppendRows menambahkan data

• Jika Lembar Kerja kosong, data ditulis mulai dari baris pertama.
• Jumlah Kolom yang ditambahkan harus sesuai dengan data yang ada agar data tetap selaras.

​

Apa format rangeAddress saat menggunakan UpdateRange untuk memperbarui Sel

​

Apa perbedaan antara GetRange dan UpdateRange

​

Cara memecahkan masalah error invalidRequest.resource.notFound

​

Apa saja batasan penggunaan DingTalk Spreadsheet API

​

Cara menangani kegagalan panggilan API dalam kode

• Muat ulang otomatis saat token kedaluwarsa: Tangkap error token tidak valid, muat ulang token secara otomatis, dan coba lagi.
• Coba lagi saat pembatasan laju: Saat error 429 dikembalikan, tunggu sebelum mencoba lagi (kami menyarankan strategi exponential backoff).
• Penanganan idempotensi: Untuk operasi tulis seperti AppendRows, perhatikan bahwa percobaan ulang dapat menyebabkan penulisan data ganda. Sertakan pengidentifikasi unik dalam data dan verifikasi dengan GetRange setelah menulis.
• Penanganan timeout: Tetapkan timeout yang wajar untuk permintaan jaringan (kami menyarankan 30 detik), dan coba lagi setelah timeout.

import time

def call_api_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except TokenExpiredError:
            refresh_token()
        except RateLimitError:
            time.sleep(2 ** attempt)
        except TimeoutError:
            time.sleep(1)
    raise Exception("The API call failed. The maximum number of retries has been reached.")