> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# よくある質問

> DingTalk スプレッドシートにはそれぞれ一意の識別子として workbookId が割り当てられています。取得方法は以下のとおりです。

## 接続関連

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

DingTalk スプレッドシートにはそれぞれ一意の識別子として `workbookId` が割り当てられています。取得方法は以下のとおりです。

* **スプレッドシートの URL から取得**：DingTalk スプレッドシートを開き、URL に含まれるドキュメントIDが `workbookId` です。

* **ドキュメント情報から取得**：スプレッドシート左上の「メニュー」→「スプレッドシート」→「ドキュメント情報」をクリックし、そこに表示されるドキュメントIDが `workbookId` です。

* **ナレッジベース API から取得**：[ノード取得](/ja/open/development/get-knowledge-base-acquisition-node) API を呼び出し、戻り値の `nodeId`（`dentryUuid`）が `workbookId` です。

### operatorId を取得する方法

`operatorId` は操作者の `unionId` です。取得手順は以下のとおりです。

1. **電話番号から userId を取得**：[電話番号でユーザーを検索](/ja/open/development/query-users-by-phone-number) API を呼び出します。
2. **userId から unionId を取得**：[ユーザー詳細を取得](/ja/open/development/query-user-details) API を呼び出し、戻り値の `unionId` が `operatorId` です。

<Warning>
  初回呼び出し時、アプリで「連絡先」関連の権限申請が必要になる場合があります。取得した `operatorId` は環境変数として保存しておき、毎回 API で取得しないようにすることを推奨します。
</Warning>

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

アクセストークンの有効期限は **7200 秒（2 時間）** です。期限切れ後は、[社内アプリの accessToken を取得](/ja/open/development/obtain-the-access-token-of-an-internal-app) API を再度呼び出して新しいトークンを取得する必要があります。

アプリ側でトークンのキャッシュと自動更新の仕組みを実装することを推奨します。

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

***

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

このエラーは `operatorId` に対応するユーザーが対象スプレッドシートの操作権限を持っていないことを示します。以下を確認してください。

* **ユーザーがスプレッドシートへのアクセス権限を持っているか**：該当ユーザーがスプレッドシートの共同編集者として追加されているか、またはスプレッドシートが所属するナレッジベースで該当ユーザーに権限が付与されているかを確認します。
* **権限タイプが一致しているか**：

  * 読み取り操作：`GetAllSheets`、`GetSheet`、`GetRange` などは `Document.Workbook.Read` 権限が必要です。
  * 書き込み操作：`AppendRows`、`UpdateRange`、`CreateSheet` などは `Document.Workbook.Write` 権限が必要です。
* **アプリが対応する権限を申請しているか**：[DingTalk オープンプラットフォーム](https://open-dev.dingtalk.io/) のアプリ管理で、該当する権限スコープを申請し承認されているかを確認します。

***

## API 利用関連

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

可能です。`sheetId` パラメーターはワークシートの **ID** または **名称（見出し）** の指定をサポートしています。例：

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

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

***

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

`AppendRows` はワークシート内の **最後のデータが存在する行** を自動的に検出し、その下に新しい行を追加します。

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

***

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

`rangeAddress` は **A1 表記法** を使用します。一般的な形式は以下のとおりです。

| 形式         | 意味   | 例                  |
| ---------- | ---- | ------------------ |
| A1         | 単一セル | 1 行 1 列目。          |
| A1:C3      | 矩形範囲 | A1 から C3 までの 9 セル。 |
| A:A        | 列全体  | A 列のすべてのセル。        |
| 1:1        | 行全体  | 1 行目のすべてのセル。       |
| A1:ZZ99999 | 大範囲  | 表全体の操作に使用。         |

***

### GetRange と UpdateRange の違いは何ですか

| 比較項目      | GetRange                                            | UpdateRange                                            |
| --------- | --------------------------------------------------- | ------------------------------------------------------ |
| HTTP メソッド | GET                                                 | PUT                                                    |
| 機能        | セル範囲の値・スタイルなどの属性を取得                                 | セル範囲の値・スタイルなどの属性を更新                                    |
| 必要な権限     | `Document.Workbook.Read`                            | `Document.Workbook.Write`                              |
| 説明ドキュメント  | [セル範囲を取得](/ja/open/development/get-cell-properties) | [セル範囲を更新](/ja/open/development/update-cell-properties) |

`GetRange` は、データ書き込み後の結果検証や、自動化フロー内でスプレッドシートのデータを読み取り後続処理を行う場合に適しています。両者は同じ `rangeAddress` パラメーター（A1 表記法）を使用してセル範囲を指定します。

***

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

このエラーはリクエストされたリソースが存在しないことを示します。よくある原因は以下のとおりです。

| シナリオ             | 想定される原因                     | 解決方法                                     |
| ---------------- | --------------------------- | ---------------------------------------- |
| workbookId が無効   | スプレッドシートが削除済み、または ID のスペルミス | workbookId を再取得します。                      |
| sheetId が無効      | ワークシートが削除済み、または名称が変更された     | `GetAllSheets` を呼び出して最新のワークシートリストを取得します。 |
| rangeAddress が無効 | セルアドレスの形式が誤っている、または範囲外      | A1 表記法の形式を確認し、スプレッドシートの範囲内であることを確認します。   |

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

| 制限項目                 | 制限値            | 説明                         |
| -------------------- | -------------- | -------------------------- |
| レート制限                | 100 回/分以下を推奨   | 単一アプリから同一スプレッドシートへの呼び出し頻度。 |
| AppendRows の 1 回の追加量 | 5000 行以下を推奨    | 超過するとタイムアウトする可能性があります。     |
| セル内容の長さ              | スプレッドシートの制限による | 長すぎるテキストは切り捨てられる可能性があります。  |
| アクセストークンの有効期限        | 7200 秒（2 時間）   | 期限切れ後は再取得が必要です。            |

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

以下のエラーハンドリング戦略の実装を推奨します。

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 呼び出しに失敗しました。最大再試行回数に達しました")
```