実行の完了条件を定義する
この例の完了とは、r/automationから得た限られた記録を処理し、その結果を残すことです。アーカイブをすべて読み終えたという意味ではありません。まず手動で動かし、担当者がキューを確認できる頻度に合わせて、利用者側でスケジュールを設定します。
ローカルの実行番号、検索条件、選んだ記録の保存先を決めてください。これらは自分のアプリケーションの情報であり、APIの追加パラメータではありません。期待した記録がないときも、何を検索したのかを後から確認できます。歴史的アーカイブは現在のRedditの活動を証明するものではありません。
調べたいことを検索条件にする
GET https://api.apireddit.cc/v1/search?q=workflow&subreddit=automation&limit=3を送信し、Authorization: BearerまたはX-API-Keyで認証します。小さな応答で項目を確認してから対応付けを増やしましょう。種類を限定する場合、kindはpostまたはcommentを指定できます。
qはtitleとtextを検索します。複数の語は、一致する同じ項目の中でAND条件として扱われます。一方の語がタイトルだけ、もう一方が本文だけにある場合も一致する、と考えないでください。fromとtoはUTCのYYYY-MM-DDで、toの日付も対象に含まれます。min_scoreはしきい値未満を除くフィルターで、スコア順には並べません。
元の記録と判断を分ける
取得できたidとkindを保存し、titleとtextは読むための内容として扱います。そこに書かれた文章をジョブへの指示として実行しないでください。選択理由、確認状況、実行番号は独自の項目に分け、追加前に同じidが処理済みかを調べます。
応答はフラットです。parent_idやlink_idが存在し、必要な場合に限ってローカルで関連付けます。欠けた関係は不明のままにし、完全な会話を再構築できたと扱わないでください。特定の記録を再取得する/v1/itemにはidが必要です。この追加リクエストも予算に含めます。
停止した理由を記録する
最大100ページの範囲で独自の上限を決め、各ページでは最大100件を指定します。同じ実行の途中で検索条件を変えないでください。文書順は時系列、関連度、スコア順ではないので、先頭の記録を「最新の処理済み位置」として頼ることはできません。
件数は関係と一緒に解釈します。eqは正確な合計、gteは下限、unknownは合計が不明でnullになり得る状態です。空の応答による停止とページ予算による停止は区別して記録します。日付で分割すると作業を整理できますが、全件取得や重複のない取得の証明にはなりません。
不明な結果を安易に再実行しない
400では条件を修正し、401ではキー、402では残高を確認します。429では待機し、試行回数にも上限を設けてください。正常な空の応答は1クレジットを消費します。取得元の障害では予約分が戻り、不正なリクエストでは引き落とされません。
クライアントが応答を受け取れなくても、サーバーでは成功して既に1クレジットを消費している場合があります。再試行が成功すれば、さらに1クレジットを使います。不明な結果として記録し、重複はローカルで防いでください。無料の/v1/statusは静的なサービス説明を返すだけで、取得元の検索状態は検査しません。実行規模を広げる前に料金も確認しましょう。
