チュートリアル: ワークフローを作成する

Portant Developer API を使用してワークフローを作成し、Webhook ソース経由で実行し、ドキュメントが作成されたときにイベントを受信する実践的な例です。すべてのリクエストには cURL を使用します。<DEVELOPER_ACCESS_TOKEN> は、Portant インテグレーションチームから提供されたトークンに置き換えてください。

ヒント: 開始する前に、Portant Workflow ウェブアプリでワークフローを構築して実行し、ワークフローの仕組みを把握しておいてください。Google Docs テンプレートを推奨します。これにより、アカウントが Google の API で正しく認証されていることも確認できます。

このチュートリアルは、Developers overview ガイドの手順を完了していることを前提としています。

ステップ 1. ワークフローを作成する

ワークフローに "Developer Workflow" という名前を付け、Workflows POST エンドポイントで作成します。

curl --location --request POST 'https://api.portant.co/v0/workflows/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Developer Workflow"
}'

リクエストが成功すると、次のような JSON ボディとともに 201 Created が返されます。

{
    "id": "wkf_<id>",
    "name": "Developer Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "INCOMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_<id>",
        "name": "Your Name",
        "email": "you@email.com"
    },
    "team": null,
    "source": {
        "id": "src_<id>",
        "sourceType": "WEBHOOK",
        "sourceFields": [],
        "webhookUrl": "https://webhooks.portant.co/<webhook_token>"
    },
    "documents": [],
    "outgoingWebhook": null,
    "createdByApi": true,
    "createdAt": "2024-08-13T17:49:28.639426+10:00",
    "updatedAt": "2024-08-13T17:49:28.659242+10:00"
}

id の値を保存してください。次のリクエストで使用します。

その ID を使って https://app.portant.co/w/wkf_<id>/ を開くと、ウェブアプリで新しいワークフローを確認できます。特に重要なフィールドは source.webhookUrl と status の 2 つです。

API 呼び出し後に Portant ウェブアプリで開かれた新しいワークフロー

source.webhookUrl は、ワークフローが完成した後にオートメーションを開始するためにデータを POST するアドレスです。こちらも保存しておいてください。

status が "INCOMPLETE" になっているのは、ワークフローにテンプレートドキュメントがまだ存在しないためです。ワークフローを実行可能にするには、ソースと少なくとも 1 つのテンプレートの両方が必要です。次のステップでテンプレートを追加します。

ステップ 2. テンプレートドキュメントを作成する

テンプレートを追加するには、既存の Google Docs ファイルをワークフローにコピーします。

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/documents/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_id": "1frlTt7Jj8HuXWHkS9o0mshLaym6NQBImsAIhw4Iiew4"
}'

file_id は、アクセス権を持つ Google Drive 上のファイルの ID です。ファイルの ID はその URL から確認できます。上記のサンプル ID はこの公開 Portant ドキュメントのものです。テスト用にそのままご利用いただけます。

レスポンスは次のようになります。

{
    "id": "doc_<id>",
    "documentType": "GOOGLE_DOCS",
    "file": {
        "id": "1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc",
        "name": "Developer Workflow - [Template]",
        "url": "https://docs.google.com/document/d/1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc/edit?usp=drivesdk",
        "mimeType": "application/vnd.google-apps.document"
    },
    "outputName": "Developer Workflow - {{Timestamp}}",
    "createPdfCopy": false,
    "removeOutput": false,
    "enablePdfPassword": false,
    "pdfPassword": "",
    "pdfPasswordPreventCopy": false,
    "previewUrl": "https://preview.portant.co/doc_LcQWshvjR9XLzQ"
}

指定したファイルのコピーを使用した新しいテンプレートがワークフローに追加されました。ドキュメントリソースには、出力ドキュメントの作成方法を変更するオプションのセットが含まれています。これらは Document エンドポイントへの PATCH リクエストで変更できます。

再度 workflow を GET すると、status が "COMPLETE" になっています。最初のオートメーションを実行する前に、イベント通知も設定しておきましょう。

ステップ 3. オートメーションイベントを受信する

オートメーションの実行時に通知を受け取るには、ワークフローに Outgoing Webhook (送信 Webhook) を登録します。テスト用には、webhook.site で一時的な Webhook を作成できます。

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/outgoing-webhook/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhookUrl": "https://webhook.site/<token>"
}'

登録した URL とともに 201 Created レスポンスが返されます。これでワークフローを実行する準備が整いました。

ステップ 4. Webhook ソースにデータを POST する

オートメーションを開始するには、ワークフローの Webhook ソース URL（ステップ 1 で返されたもの）に JSON ボディを POST してください。

curl --location --request POST 'https://webhooks.portant.co/<webhook_address>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Name": "Jeremy the Koala"
}'

エンドポイントは空の JSON ボディとともに 200 OK を返します。1 分以内に、webhook.site の受信ボックスに Google Drive 内の新しいドキュメントへのリンクを含むイベントが表示されます。

Portant Workflow ウェブアプリでは、新しい出力がワークフローの outputs（出力）ページにも表示されます。以上で、Developer API を通じて初めてのワークフローの作成と実行が完了です。

各エンドポイントとリソースの詳細については、API リファレンスの残りの部分を参照してください。ご質問や機能リクエストがある場合は、カスタマーサクセスまたはインテグレーションチームにお問い合わせください。

（そうです、Jeremy は Portant のマスコットです。🐨）