APIクライアント

SUMMARY

• WorkatoのAPIクライアントは、APIエンドポイントへのカスタマイズ可能なアクセスを提供し、セキュリティを向上させます。
• APIクライアントを作成するには、クライアントの役割とアクセスレベルを定義する必要があります。一度表示されたAPIトークンを作成した後は、安全に保存して保管してください。
• クライアントと役割の更新は即座に反映されます。クライアントまたは役割を削除すると、関連するAPIリクエストは即座に拒否されます。
• セキュリティのためにAPIクライアントトークンを更新することができます。

APIクライアントを使用すると、各エンドポイントへの設定可能なアクセスを持つ複数のクライアントを作成することで、セキュリティのベストプラクティスを強制することができます。APIクライアントのリクエストには、認証のための単一のヘッダーが必要です。

LEGACY FULL ACCESS API KEYS

APIクライアントの前に、WorkatoのAPIはレガシーのフルアクセスAPIキーとメールをリクエストヘッダーまたはクエリパラメーターに使用してリクエストを認証していました。このレガシー機能は引き続きサポートされていますが、認証にはAPIクライアントへの移行を強くお勧めします。詳細を見る

移行と削除は異なることに注意してください。レガシーAPIクライアントを削除すると、APIキーとメールを復元することはできず、このAPIキーとメールを使用したリクエストは拒否されます。

APIクライアントの利点

Workatoの開発者および埋め込みAPIを使用すると、Workatoワークスペースを自動化することができます。これには、開発から本番環境へのレシピマニフェストの展開や、ネットワーク環境内での新しいオンプレミスエージェントの展開などが含まれます。APIクライアントを使用すると、各アプリケーションのユースケースに応じたAPIアクセスをプロビジョニングすることで、組織のセキュリティを向上させることができます。

APIクライアントと割り当て可能な役割を使用すると、次のレベルでAPIアクセスのスコープを設定できます：

• APIクライアントには、それらが対話できるAPIエンドポイントを定義する役割が割り当てられます。
• APIクライアントには、DEV、TEST、またはPRODなどの環境が割り当てられます。環境はアドオン機能であり、ワークスペースで利用できない場合があります。
• APIクライアントにはプロジェクトが割り当てられます。これにより、特定のプロジェクト内の特定のアセットへのAPIアクセスが制限されます。

ワークスペース内のさまざまなプロジェクトやAPIエンドポイントに特化した個々のクライアントを作成することができます。Workato Developer APIクライアントトークンは、Github Secret Scanningと統合されています。

クライアントの役割を作成する

APIクライアントを作成する前に、クライアントの役割を作成する必要があります。クライアントの役割を作成することで、APIクライアントがアクセスできるエンドポイントを設定することができます。

クライアントの役割を作成するには、次の手順に従ってください：

1

ワークスペースアクセスに移動します。

2

APIクライアント > クライアントの役割 > クライアントの役割を追加を選択します。 新しいクライアントの役割を作成する

3

新しいクライアントの役割に名前を入力します。たとえば、「レシピオペレーター」という名前を使用して、レシピAPIエンドポイントと対話できる役割を作成します。

4

各セクションの下にある必要なエンドポイントを役割に選択します。ワークスペースで利用可能なすべてのWorkato APIエンドポイントがこれらのセクションにリストされています。

5

選択が完了したら、役割を保存します。必要に応じて、クライアントの役割を編集することができます。

APIクライアントの作成

APIクライアントを作成するには、次の手順に従ってください：

1

ワークスペースアクセスに移動します。

2

APIクライアント > APIクライアントの作成を選択します。

新しいAPIクライアントを作成する

3

新しいクライアントの名前を入力します。たとえば、「営業とマーケティング - レシピオペレーター」という名前を使用して、営業とマーケティングチームがAPIを介してレシピを操作するために使用するAPIクライアントを作成します。

4

適切なクライアントの役割を選択します。クライアントの役割によって、APIクライアントがアクセスできるエンドポイントが決まります。

5

ワークスペースで環境が有効になっている場合は、APIクライアントがアクセスできる環境を選択します。

6

APIクライアントがアクセスできるプロジェクトを選択します。このAPIクライアントを使用するチームに関連するプロジェクトのみを選択してください。プロジェクトへのアクセスルールは、connections、recipes、folders、lookup tables、properties、API Platform collections、API Platform API Clientsなど、プロジェクトにスコープを設定できるすべてのアセットに適用されます。

WARNING

埋め込みパートナー向けのAPIクライアントは、埋め込みAPIにアクセスできるため、すべての顧客ワークスペースとプロジェクトにアクセスできます。

7

オプションで、このトークンを使用してAPIリクエストを行うことができる許可されたIP範囲を追加します。静的サーバーからAPIを呼び出す場合、これによりWorkatoの開発者APIへのアクセスがさらに安全になります。

8

APIクライアントの作成後に表示されるAPIトークンを、AWS Secrets Managerなどの安全な場所に保存してください。APIトークンを再度取得することはできません。

9

設定が完了したら、APIクライアントを保存します。必要に応じて、APIクライアントを編集することができます。

APIクライアントの編集

APIクライアントの編集は即座に適用されます。

APIクライアントを編集するには、以下の手順を実行します。

1

ワークスペースアクセスに移動します。

2

APIクライアント > 編集したいAPIクライアントを選択します。

3

クライアントロールを変更し、プロジェクトアクセスを編集します。これにより、関連するAPIクライアントからのすべての受信APIリクエストに即座に影響があります。

4

変更内容を保存します。

APIクライアントトークンの更新

APIクライアントを作成した後、既存のクライアントのために新しいAPIトークンを再生成することができます。APIクライアントトークンを更新するには、以下の手順を実行します。

1

ワークスペースアクセスに移動します。

2

APIクライアント > 編集したいAPIクライアントを選択します。

3

ページの右上隅にある更新アイコンを選択します。

APIクライアントトークンを更新するために更新アイコンを選択する

4

APIトークン再生成モーダルで、トークンを再生成を選択します。APIトークンを再生成すると、以前のAPIトークンを使用したAPI呼び出しは失敗します。

5

新しいAPIトークンをAWS Secrets Managerなどの安全な場所に保存します。このAPIトークンを再度取得することはできません。

6

完了を選択して、APIクライアントの編集に戻ります。

新しいトークンを生成すると、以前のAPIトークンは無効になります。旧バージョンのAPIクライアントトークンは再生成できません。

カスタムスクリプトやトークンを平文でGitHubの公開リポジトリやドキュメントなどの公開ウェブサイトにアップロードするアプリケーションを扱う場合、ユーザーエラーによりトークンが危険にさらされる可能性があります。

APIクライアントまたはクライアントロールの削除

APIクライアントまたはクライアントロールを削除する際は注意してください。

• 削除されたAPIクライアント： 削除されたAPIクライアントのAPIトークンを使用するすべての受信リクエストは拒否されます。

• 削除されたクライアントロール： 関連するAPIクライアントからのすべての受信リクエストは拒否されます。

APIクライアントとクライアントロールの管理に関するFAQ

1. クライアントロールはどのように設定すべきですか？

クライアントロールは使用ケースを考慮して設定する必要があります。たとえば、「レシピオペレーター」クライアントロールは、レシピの開始/停止へのエンドポイントアクセスを持つ場合がありますが、「プロジェクトデプロイメント」クライアントロールは、レシピライフサイクル管理や環境プロパティのエンドポイントへのアクセスを持つ場合があります。これは、APIクライアントレベルでのプロジェクトスコープと組み合わせて、使用ケースとプロジェクトの両方にアクセスを制限するために使用することができます。

ベストプラクティスとして、クライアントロールの定義においては、最小特権の原則を適用することが推奨されます。

2. APIクライアントはどのように設定すべきですか？

APIクライアントは使用ケースとプロジェクトを考慮して設定します。たとえば、「営業とマーケティング - レシピオペレーター」というAPIクライアントは、営業とマーケティングチーム専用にプロビジョニングすることができます。APIクライアントの設定では、アクセス権限を定義する際に具体的になることができます。これによりセキュリティが向上しますが、APIトークンの管理が複雑になるため、注意が必要です。

3. APIクライアントトークンをどこに保存すべきですか？

APIクライアントトークンは一度表示されると、紛失した場合は永久に失われます。APIクライアントを回復するには、トークンを再生成する必要があります。

APIトークンを管理されたアクセスが制御された安全な場所に保存するようにしてください。特に異なるチーム向けに複数のトークンを生成する予定がある場合は、AWS Secrets Managerなどのツールを検討することをお勧めします。

4. APIクライアントへのアクセス権限は誰が持っており、アクセスを制御するにはどうすればよいですか？

ワークスペースのすべての管理者はAPIクライアントにアクセスできます。この権限は「ワークスペースアクセス」の管理者ロールで定義されます。WorkatoのAPIを使用した既存の自動化ワークフローに影響を与える可能性があるため、ユーザーを管理者として追加する際には注意が必要です。

チーム内でカスタムロールを作成する際には、「ワークスペースアクセス」セクションのAPIクライアントを選択し、APIクライアントへのアクセスを定義することができます。このカスタムロールに割り当てられたユーザーは、APIクライアントツールへの完全なアクセス権を持つことになります。

5. 「TEST」と「PROD」の環境で一部のエンドポイントが互換性がないのはなぜですか？

Workatoの特定のAPIエンドポイントは、「DEV」環境のみで利用可能です。環境として「プロジェクトデプロイメント」と「ワークスペースの共同作業者」があります。これは、「DEV」環境からのみこれらのツールを管理できるためです。