HTTP API

既存のHTTP APIで認証し、ツールを検出して変更を確定します。

製品APIのリクエストは、https://influence.soなどの信頼できるInfluenceオリジンに送信します。ドキュメントのドメインでは製品APIのリクエストを受け付けません。以下のパスをそのまま使い、クエリパラメータは付けないでください。

必要な権限のAPIキーを作成する

Influenceの設定から「アプリと自動化」→「APIキー」を開き、必要な権限と有効期限を選びます。キーは一度しか表示されません。シークレットストアにPUBLISH_API_TOKENとして保存してください。Authorization: Bearer …で送信し、URL、リクエスト本文、チャットには含めないでください。不要になったら失効させます。

ツールを検出してデータを読み取る

PUBLISH_API_URLに信頼できるオリジンを設定します。以下の例は、プロセスにPUBLISH_API_TOKENが渡されていることを前提とします。accountListにはintegrations:readが必要です。次のページは返されたページング用フィールドに従って取得してください。

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

リクエストのパス

メソッド	パス	用途
`GET`	`/api/v1/tools`	この認証情報で利用できるツールを取得します。
`POST`	`/api/v1/tools/{tool}/call`	読み取り専用ツールを呼び出します。
`POST`	`/api/v1/tools/{tool}/prepare`	指定どおりの変更を実行せずに準備します。
`POST`	`/api/v1/tools/{tool}/confirm`	準備済みの変更を確定します。
`POST`	`/api/v1/media/import`	準備済みの小さな画像のバイナリアップロードを確定します。

JSONのツールリクエストにはContent-Type: application/jsonを指定し、本文にはinputのみを含めます：{"input":{…}}。各ツールの入力スキーマは現在のカタログで確認できます。

変更を準備して確定する

実行したい操作の正確な入力を/prepareに送信します。成功するとstatus: "confirmation_required"、confirmationCapability、expiresAt、inputDigestと、省略可能なsummaryが返ります。
有効期限内に、同じ入力を/confirmに送信します。返された確認用の値をX-Publish-Confirmationに、クライアントで新たに生成したキーをIdempotency-Keyに指定します。
入力、確認用の値、キーを一緒に保持します。確認処理が中断されたり結果が不明になったりした場合は、同じリクエストにこの3つを再利用してください。結果不明の操作を復旧するために、代わりの操作を新しく準備しないでください。

冪等性キーはA–Z、a–z、0–9、.、_、:、-の16〜200文字で構成します。確認用の値は解釈せずに扱う機密情報です。/callや/prepareにキーを送っても、確定処理を予約することにはなりません。

リクエストの確定と公開の承認は別の手順です。公開や日時変更では、最新の内容を含む完全なレビューを作成して表示します。テキストの公開には、その後の新たな承認が必要です。画像や動画は、対応するレビュー画面かログイン後のInfluenceで本人が実物を確認して承認する必要があります。レビューの準備だけでは公開されません。次の操作の前に保存された結果を確認してください。needs_reviewでは再送せず、何が起きたかを確認します。

エラーと結果不明の操作を扱う

HTTPステータスと本文の両方を確認します。成功時は{"ok":true,"toolName":"…","output":{…}}が返ります。ツールの失敗は{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}で、HTTP 200の場合もあります。通信処理の失敗は{"error":{"code":"…","message":"…","retryable":false}}となり、okやtoolNameは含まれません。

401は認証が必要な状態です。有効期限や失効を確認してください。権限不足には適切な許可が必要で、リクエストを繰り返しても解決しません。503はその環境でAPIを利用できない状態です。返されたエラーと再試行の案内に従ってください。タイムアウトは変更の失敗を意味しません。確認データを保持し、再送前に現在の状態を読み取ります。受付済み、予約済み、公開済みは異なる結果です。

メディアをアップロードする

ローカルファイルにはSDKのuploadMediaかCLIのmedia:uploadを推奨します。同じ分割アップロードツールを使い、再試行でもclientKeyを保持します。添付できるのは、準備完了でassetIdを持つ結果だけです。許可されたHTTPSファイル参照にはmediaImportを使います。ローカルパスはダウンロードURLではありません。

POST /api/v1/media/importは既存の小さな画像用の転送に対応します。正確なアップロード記述子でmediaImportを準備し、同じバイト列をapplication/octet-streamで送ります。X-Publish-Confirmation、Idempotency-Key、URIエンコードしたJSON記述子を持つX-Publish-Uploadを含めます。サイズとSHA-256がバイト列と一致する必要があります。上限は3 MiBです。それより大きい対応ファイルにはアップロードヘルパーを使ってください。アップロードによって公開が承認されることはありません。

APIリファレンスを開く、またはOpenAPI仕様をダウンロードする。