よくある質問

​

接続関連

​

スプレッドシートの workbookId を取得する方法

• スプレッドシートの URL から取得：DingTalk スプレッドシートを開き、URL に含まれるドキュメントIDが workbookId です。
• ドキュメント情報から取得：スプレッドシート左上の「メニュー」→「スプレッドシート」→「ドキュメント情報」をクリックし、そこに表示されるドキュメントIDが workbookId です。
• ナレッジベース API から取得：ノード取得 API を呼び出し、戻り値の nodeId（dentryUuid）が workbookId です。

​

operatorId を取得する方法

1. 電話番号から userId を取得：電話番号でユーザーを検索 API を呼び出します。
2. userId から unionId を取得：ユーザー詳細を取得 API を呼び出し、戻り値の unionId が operatorId です。

​

アクセストークンが期限切れになった場合の対処方法

• トークンとその有効期限をキャッシュする。
• 期限切れ 5 分前に能動的に更新する。
• API がトークン無効エラーを返した場合、直ちに更新して再試行する。

​

API 呼び出し時に The operator has no permission エラーが発生した場合の対処方法

• ユーザーがスプレッドシートへのアクセス権限を持っているか：該当ユーザーがスプレッドシートの共同編集者として追加されているか、またはスプレッドシートが所属するナレッジベースで該当ユーザーに権限が付与されているかを確認します。
• 権限タイプが一致しているか：
  • 読み取り操作：GetAllSheets、GetSheet、GetRange などは Document.Workbook.Read 権限が必要です。
  • 書き込み操作：AppendRows、UpdateRange、CreateSheet などは Document.Workbook.Write 権限が必要です。
• アプリが対応する権限を申請しているか：DingTalk オープンプラットフォーム のアプリ管理で、該当する権限スコープを申請し承認されているかを確認します。

​

API 利用関連

​

sheetId パラメーターにワークシート名を指定できますか

• ID 指定：Sheet1、システムが生成した ID。
• 名称指定：売上データ、ユーザーがカスタム設定したワークシートの見出し。

推奨：名称はユーザーによって変更される可能性があるため、ワークシート ID の使用を優先してください。GetAllSheets API ですべてのワークシートの ID と名称を取得できます。

​

AppendRows でデータを追加する際、データはどこに書き込まれますか

• ワークシートが空の場合、データは 1 行目から書き込まれます。
• 追加する列数は既存データの列数と一致させ、データの揃えを保つようにしてください。

​

UpdateRange でセルを更新する際、rangeAddress の形式は何ですか

​

GetRange と UpdateRange の違いは何ですか

​

API 呼び出しで invalidRequest.resource.notFound が返された場合の調査方法

​

DingTalk スプレッドシート API の利用制限

​

コード内で API 呼び出しに失敗した場合のハンドリング方法

• トークン期限切れ時の自動更新：トークン無効エラーをキャッチし、自動更新後に再試行します。
• レート制限時の再試行：429 エラーを受信した場合、一定時間待機してから再試行します（指数バックオフ戦略の使用を推奨）。
• 冪等性の確保：書き込み操作（AppendRows など）では、再試行によりデータが重複して書き込まれる可能性があることに注意してください。データに一意の識別子を含め、書き込み後 GetRange で検証することを推奨します。
• タイムアウト処理：ネットワークリクエストには適切なタイムアウト時間（30 秒を推奨）を設定し、タイムアウト後に再試行します。

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("API 呼び出しに失敗しました。最大再試行回数に達しました")