リクエストが発生する操作を書き出す
ハイキングアプリにオフライン地図の議論を読む機能を設けるとき、まず費用が返されるデータ量ではなく、取得リクエストに結び付くと理解します。正常な検索リクエスト1回は、3レコードでも100レコードでも空の一覧でも1クレジットです。ページを小さくすると読みやすくなる可能性はありますが、そのリクエストのクレジット単価は下がりません。
実際にサービスへ届く操作を図にします。最初の検索、要求された次ページ、明示的な再取得、1件の照会は、それぞれ別の取得になり得ます。読み込み済みの文章をスクロールするだけなら新しいリクエストではありません。バックエンドが1回のボタン操作を複数の呼び出しに展開する場合、その操作が1クレジットとは限りません。
仮の1日を計算する
以下は計画用の例であり、観測した通信量や利用予測ではありません。最初のページの取得120回、追加ページ30回、再取得10回が正常に完了したとします。正常リクエストは160回、消費は160クレジットで、記載の単価では$0.16に相当します。最初のページのうち20回が空でも、正常に完了しているため合計は160クレジットのままです。
誰も読まない場合も含め、最初の検索ごとに3ページを自動取得すると仮定します。再取得を数える前に360リクエストとなり、最初の例の初回検索と意図した追加ページを合わせた150回より多くなります。これは明記した仮定による計算であり、実際の利用者の行動の証拠ではありません。実装後は、自分で測定したリクエストログに基づく数値に置き換えてください。
利用単価と購入額を分ける
標準単価は、正常な取得リクエスト1,000回につき$1です。最低有料チャージ額は$50で、50,000有料クレジットが得られます。定期契約はなく、有料クレジットに有効期限もありません。したがって仮の1日$0.16は残高の消費額を示すものであり、$0.16だけチャージできるという意味ではありません。
任意の100クレジット試用には、ネットワーク共通の不正利用防止上の条件があり、有料購入の換算とは別です。すべての登録で付与されると考えたり、無料APIとして紹介したりしないでください。ログインして請求書を作り、その正確な支払額、受取先、トークン、ネットワークを使います。アカウントと支払いの手順は「キーとクレジット」にあります。
失敗と結果不明を区別する
HTTP 400、401、402、429は、取得用クレジットを予約する前に拒否されます。それぞれ入力の不備、キーの欠如または無効、クレジット不足、レート制限を示します。上流リクエストが失敗した場合は予約済みクレジットが解放されますが、照合処理が保留になることもあります。すべてのエラーを、以前の課金が直ちに返還される処理と説明しないでください。
送信後にアプリがレスポンスを失うと、サーバーが正常な取得を完了したか分からない場合があります。再試行は別のリクエストであり、無料の続きとは保証されません。結果が不明であることを記録し、クエリを保持し、自動再試行の集中を避けます。照合に使えるよう、アカウント画面には成功・保留・返還済みのリクエスト件数が表示されます。
機能側でも上限を決める
各クエリでは1–100ページ、各リクエストでは最大100レコードを要求できます。これはサービスの上限であり、全ページ取得の推奨ではありません。対話的な閲覧では、アプリ独自に小さなページ予算を設定し、さらに取得する前に利用者へ確認できます。空のページを探して要求を繰り返すのではなく、pagination.has_moreと取得範囲の最終境界に従ってください。
最大10,000レコードの取得範囲を、必ず得られる件数として数えないでください。レスポンスが空の場合も、フィールドが欠ける場合もあり、アーカイブは完全な収録を約束しません。/v1/statusは無料ですが、アカウント残高を返さず、検索の健全性も調べません。ローカルのカウンターにも照合が必要であり、レスポンスを失ったリクエストが無料だったとは証明できません。
読み手に本当に必要な選択を見直す
提案するハイキング用パネルでは、短い最初のページと、意図した「さらに表示」だけで参照資料を比べられるかもしれません。アプリに保存済みの内容を保存し直したり開いたりするとき、黙って再取得しないでください。利用者が明示的に再確認を求めたら、新しい照会であることを説明し、取得できない結果にも対応します。
上限や表示の調整は、自分の通信実績に基づいて判断してください。計画用の例を、利用者当たりの費用、継続率、性能の保証に変えないようにします。取得範囲を限るページネーションと端末内の閲覧リストは/ja/#field-notesを参照してください。
