OAuth v2 のワークフロー

インストール

npm install --global @anakonn/ankk@0.5.1
ankk --version

ログインしてブランドを選ぶ

ANKK v2 はブラウザー OAuth を通じてユーザーアカウントを使用します。各リクエストには既存の権限が適用されます。アプリを接続しても、ブランドへの追加権限は付与されません。作業時にブランドを選んでください。OAuth の認可ではブランドを選択しません。

Node.js 24 以降で CLI 0.5.1 を使用します。以下の公開クライアント ID は ANKK CLI を識別するもので、秘密情報ではありません。

export ANKK_OAUTH_CLIENT_ID=ankk-cli-production

ankk --json auth login --environment production
ankk auth status --environment production --connection OAUTH_CONNECTION_ID
ankk --json brands list --environment production --connection OAUTH_CONNECTION_ID --all
ankk --json connections list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

大文字の識別子は、自分のリクエストから返された ID に置き換えてください。OAuth 接続 ID はログインを選択します。SNS アカウント ID は投稿先を識別し、OAuth 接続 ID とプロバイダーのアカウント ID のどちらとも異なります。一連の手順では同じ環境とブランドを使用します。例では、ローカルの既定ブランドを設定済みでも両方を明示します。

ブラウザーが自動で開かない端末では、ankk auth login --environment production --device --no-open を実行し、表示される確認手順に従ってください。トークンは OS の認証情報ストアに保存されます。ストアを利用できない場合は、ログイン前に復旧してください。トークンをチャットに貼り付けたり、公開用 JSON ファイルに保存したりしないでください。

成果と保存済み投稿を読む

ankk --json analytics get --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z
ankk --json posts list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

実際の集計期間を選びます。開始時刻を含み、終了時刻は含みません。タイムスタンプは UTC です。問い合わせ前にユーザーの現地日付を UTC に変換してください。--sns-account SNS_ACCOUNT_ID を追加すると、結果を1つのアカウントに絞れます。

結果は保存された観測データを表します。期間を比較する前に、対象範囲と観測時刻を確認してください。欠損データはゼロではありません。アカウントの最新スナップショットには固有の測定時刻があり、必ずしも期間合計ではありません。Instagram の指定期間インサイトと蓄積された観測値は別のものです。読み取りはプロバイダーからの収集を開始しません。posts refresh は投稿・コメントデータに対する別の操作で、分析の更新要求ではありません。

一覧はカーソルを使用します。--all は後続ページを取得しますが、取得中にデータが変わり得るため、結果はスナップショットではありません。カーソルが期限切れになったら、結果が不完全であることを伝え、意図的に新しい一覧取得を開始してください。古いページと黙って結合してはいけません。

公開前にファイルを準備する

ankk --json media create-upload --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file ./photo.jpg --idempotency-key UPLOAD_KEY
ankk --json media complete-upload MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --idempotency-key INSPECTION_KEY --wait --wait-timeout 180
ankk --json media get MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID

最初のコマンドはファイルを登録して転送します。転送が失敗した場合や応答が不確かな場合も、メディア ID を保存してください。2つ目は検査を要求します。メディアの最終状態が ready の場合にのみ使用してください。これらの手順では公開されません。メディアは同じブランド内で再利用できます。別のブランドには個別にアップロードしてください。

アップロード URL だけが期限切れになった場合は、同じ環境、ログイン、ブランドで media refresh-upload MEDIA_ID を使います。新しい URL は元の業務期限を延長せず、ファイルも置き換えません。バイト列が異なるファイルには新しいメディアのアップロードが必要です。署名付き転送 URL は認証情報として扱い、共有する会話記録に含めないでください。ファイル転送に対応しないクライアントでは、返されたブラウザー進行 URL を開き、ログインしてファイルを選び、同じメディア ID で戻って準備完了を確認できます。

確認して公開する

AI が準備した内容を公開する前に、ブランド、アカウント、全文、スレッド各部分の順序、添付ファイル、プロバイダー別オプション、実行時刻を確認してください。その正確な実行内容が既に承認されていれば、再承認は不要です。分析や下書きだけの依頼は公開の承認ではありません。

次の最小限の即時公開入力を publish.json として保存してください。提案したテキストと画像の組み合わせに対応するアカウントを選びます。サーバーは現在の機能対応、メディアの準備状態、権限を再確認します。例中の英語の本文は、実際に承認された全文に置き換えてください。

{
  "scheduled_at": null,
  "targets": [
    {
      "sns_account_id": "SNS_ACCOUNT_ID",
      "text": "The exact text you approved",
      "media_ids": ["MEDIA_ID"]
    }
  ]
}

ankk --json contents publish --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file publish.json --idempotency-key PUBLICATION_KEY

送信前に、この実行内容に固有のキーを選んで保持してください。応答が不確かな場合は、API、CLI、MCP 間を切り替えても、まったく同じキーと入力を再利用します。接続がタイムアウトしただけで別の公開を作成してはいけません。同じキーで入力を変更すると競合になります。期限切れのキーは新しい処理を作成しません。新しい実行内容を意図的に開始する前に、以前の結果を確認してください。

予約の場合は、scheduled_at: null を承認済みの将来の UTC 時刻、例えば 2026-12-01T09:00:00Z に置き換えます。この例示用の日付は使用前に変更し、将来であることを確認してください。登録が完了すると別の publish_operation_id が返りますが、予約した SNS 投稿が公開されたことは意味しません。

結果を追跡する

ankk --json operations get OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --wait --wait-timeout 180

即時公開では返された操作 ID を追跡します。予約では実行時刻に publish_operation_id を追跡します。待機は任意でローカルの動作です。CLI 終了コード 10 は待機上限の超過、130 は待機の中断を意味します。どちらもサーバーのタスクを取り消しません。同じ操作の読み取りを続けてください。待機時の終了コード 11 は、失敗、キャンセル、または一部成功の最終結果を示すので、アカウント別結果を確認します。通常の状態照会は、失敗した操作を報告していても終了コード 0 になり得ます。スクリプトは応答の状態も確認する必要があります。

アカウントごとに結果を報告してください。成功した投稿と URL を保持します。順序付きの posts 配列には確認済みのスレッド投稿が含まれ、代表の post_url だけではスレッド全体を表さないことがあります。URL がないことや状態が未解決であることは、プロバイダー側で何も作成されなかった証拠ではありません。照合中や不明の結果は、既存タスクが証拠を提供するまで未解決として扱ってください。

予約を変更する、失敗から復旧する

内容や時刻を変更する前に、同じ環境、ログイン、ブランドで contents get CONTENT_ID を読みます。その現在のバージョンを --expected-version として渡してください。contents update は対象となる未開始の投稿先を編集し、contents reschedule はその UTC 予定時刻を変更します。バージョン競合では再取得と再確認が必要です。黙って上書きしてはいけません。contents cancel は取り消しを要求します。返された公開操作を、取り消しが確認されるまで調べてください。競合の結果、実行が先になる可能性があります。

現在 can_retry と表示される失敗アカウントだけを選んで再試行してください。

ankk --json contents retry ORIGINAL_OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --accounts FAILED_SNS_ACCOUNT_ID --idempotency-key RETRY_KEY

これは新しい実行内容であり、既に承認範囲に含まれる場合を除き、適切な新しいキーとユーザー承認が必要です。応答が不確かな場合も、その再試行キーを保持します。再試行は保存済みの内容を使って可能な限り早く実行され、成功済みまたは結果不明の投稿先を再公開しません。新しい将来の予約には、編集可能な入力だけを返す contents duplicate を使用します。それを確認して、新しく承認された公開を送信してください。

対象となる失敗キュー項目を破棄すると作業キューから非表示になりますが、投稿の削除、実行履歴の消去、再試行は行われません。一括キャンセルは受付済みと拒否済みのグループを同時に返すことがあります。受付済みの各公開操作を追跡してください。一括破棄は同期的に完了します。新しい操作を待たず、処理結果の破棄済みと拒否済みのグループを確認します。どちらも終了コードを全件成功か全件失敗かの結果とみなさず、処理結果全体を読んでください。

リクエストエラーに対応して接続を解除する

構造化されたエラーコード、リクエスト ID、存在する場合の操作 ID、next_action、retry_at を読みます。認証を復旧したら元の操作に戻ります。権限エラーには正当なアクセス権が必要で、別のインターフェースへの変更では解決しません。レート制限と機能制約を守ってください。リクエストが再試行可能であっても、新しい公開やキーの置き換えが認可されるわけではありません。

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

ログアウトは、サーバーでの失効とローカル認証情報の削除を別々に報告します。サーバーの失効が未確認なら、ANKK の設定または別の有効な接続から古い接続を失効させてください。OAuth 接続を削除しても、受付済みの公開はキャンセルされず、ブランド所有のメディアも削除されません。

MCP と Skills を使う

MCP は https://api.ankk.app/mcp/v2 でユーザー OAuth を使用します。ホストには登録済みクライアントが必要で、URL の入力だけでは接続は完了しません。ChatGPT・Claude の公式ディレクトリには未登録です。カードが使えない場合はテキストと構造化結果を使い、会話の要約だけでなく成績値と観測時刻を確認してください。

Skills は手順を提供し、権限や認証情報は付与しません。以下の固定候補タグをインストールし、ブランド、承認、処理の最終結果を確認します。

npx skills add https://github.com/Anakonn/ankk-skills/tree/v0.1.0-rc.1 --skill ankk-analyze --skill ankk-publish