API の概要

重要

APIを初めて使用する場合は、「 APIを開始する」のヘルプページを参照してください。

重要

22.1 リリース以降、当社は、FIPS に準拠していない SHA1 ハッシュを必要とするレガシーの公開 OAuth1 API エンドポイントを削除しました。この削除では、レガシーのWCF(Windows Communication Framework) エンドポイント、こうしたレガシーエンドポイントのSwagger、およびOAuth1ミドルウェアも対象になります。OAuth1 エンドポイントの代わりに、21.4 でリリースされたレガシー API の OAuth2 エンドポイント (FIPS 準拠) を使用できます。OAuth2 API では、OAuth1 API と同じ機能を利用できます。

サブスクリプション、V1 および V2 エンドポイントは、今後も OAuth2 でサポートされる予定です。

変換とその影響の詳細については、「 OAuth1からOAuth2への移行手順」ヘルプページまたは「移行手順」を参照してください。

Server API は、次の 5 つの API で構成されています。

Subscription API : ユーザーがサブスクリプション、ワークフロー、スケジュール(ジョブ)を操作するためのエンドポイントです。
User V2 API : ユーザーが資格情報、入力ファイル、スケジュール (ジョブ) を操作するためのエンドポイントです。
Admin V1 API : 管理者が管理インターフェースからリソースを取得するためのエンドポイントです。
Admin V2 API : 管理者が管理インターフェースからリソースを取得するためのエンドポイントのバージョン2です。
Admin V3 API : エンドポイントのバージョン 3 です。このバージョンでは OAuth 2 が使用されています。

注記

V3 API エンドポイントでの新機能追加に加え、V1、サブスクリプション、V2 エンドポイントも OAuth 2 で使用できるようになりました。これまで使用していたエンドポイントと同じエンドポイントが、新しいベースアドレスで OAuth 2 に対応しました。

Web API アドレスは、OAuth 2 を使用する V1、V2、V3 に対してのみ設定できます。OAuth 1 を使用した V1、V2 の API ドキュメントの場合、アドレスは http://{ServerHostname}/gallery/api-docs/ となります。

The Web API address can be set up in System Settings.

Server API リファレンスドキュメントの利用

すべての Server API エンドポイントに関する完全なリファレンスドキュメントは、Swaggerで提供されています。

Server UIには、Server APIリファレンスドキュメントにアクセスできる場所が2か所あります。

上部ツールバーの疑問符アイコンを選択し、 [ API ドキュメント ] を選択します。
ユーザー名を選択し、[ My profile ]>[ Keys ] を選択します。API キーの横に API ドキュメントへのリンクがあります。

Server API の API リファレンスドキュメントは、URL: http(s)://serverhostname.domain/webapi/swagger を使用してアクセスすることもできます。

Server API リファレンスドキュメントへの認証

Server API のドキュメントは、パラメーターを入力してレスポンスを確認することができるインタラクティブなものとなっています。このインタラクティブ機能を使用するには、認証を行う必要があります。これを行うには、次の手順を実行します。

Server UIでユーザー名を選択し、[ マイプロフィール ] > [ キー ] を選択します。認証したいAPIのAPIキーをコピーし、[ API キー ] フィールドと [ Shared Secret ] (共有暗号鍵) フィールドに貼り付けます。キーは [ Saved ] (保存済み) と表示されます。
実行したい呼び出しを選択し、パラメーターを入力して、[ 試してみる ] を選択します。

API キーと API アクセス

管理者(Server管理者)は、ユーザーにAPIへのアクセスを許可する必要があります。詳細については、「 Allow User Access to the Server API (Server API へのユーザーアクセスを許可する) 」を参照してください。API へのユーザーアクセスを許可すると、ユーザーは [ My Profile ] ページの [ Keys ] タブで API キーを見つけることができるようになります。APIキーにアクセスするには、ユーザー名を選択し、 [ マイプロフィール ] > [ キー ] を選択します。

管理者ロールを有するユーザーは、 APIアクセス キーを使用して、Subscription API、User V2 API、V1 Admin V1 API、V2 Admin V2 API、V3 APIを含むすべてのAPIにアクセスすることができます。

すべての非管理者ユーザーは、 APIアクセス キーを使用してSubscription APIとUser V2 APIにアクセスできます。

すべてのユーザーが Private Studio API キーを使用してサブスクリプションAPIにアクセスできます。

API エンドポイントの構築

API エンドポイントを構築するには、 <hostname>/webapi/ というスキーマを使用します。

認証

「 Server API Configuration and Authorization (Server API の設定と認証) 」の記事を参照してください。

API エンドポイントとパラメーター

このセクションでは、次のエンドポイントについて詳しく説明します。

監査ログエンドポイント

Server は、以下のシステムエンティティに対する変更を追跡します。

AppInfo (ワークフロー)
コレクション (Collection)
資格情報
Subscription (サブスクリプション)
ユーザー
ユーザーグループ

Server API を使用して記録したイベントを取得

これらのエンティティが更新されると、AuditEventレコードが作成されます。これらのレコードは、パブリック管理者 API エンドポイントを介して返すことができます。

エンドポイント

AuditEvents のエンドポイント: GET /admin/v1/auditlog/

必須のクエリーパラメーター

entity: (文字列) 照会する監査ログエンティティ。
page: (整数) 返すページ。
pageSize: (整数)各ページで返すレコードの数。

応答は、監査イベントレコードの配列になります。

[
  {
    "id": "",
    "entity": "",
    "entityId": "",
    "userId": "",
    "timestamp": "Date",
    "event": "",
    "oldValues": "",
    "newValues": ""
  }
]

返されるプロパティは次のように定義されます。

id: 監査イベント ID。
entity: エンティティの名前。
entityId: エンティティのエンティティ ID。
userId: エンティティを変更したユーザーの ID。
timestamp: 監査イベントレコードが作成された日時。
event: 発生したイベント (挿入、更新、削除)。
oldValues: 更新前に更新されたプロパティの値。
newValues: 更新後に更新されたプロパティの値。

InputFiles エンドポイント

API経由でファイル参照ツールを使用するワークフローを実行するには、 /user/v2/inputfilesエンドポイントを使用してファイルをアップロードします。ファイル参照ツール

まず、 /user/v2/InputFiles エンドポイントに multipart/form-data POST リクエストを行い、一時ファイルを公開します。必須の form-data セクションの名前は inputFileです。
```
curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \
--form 'inputFile=@/file/path/filename.csv' 
```

次に、 /user/v2/workflows/{appId}/jobs/エンドポイントにPOSTを行います。

その後、質問オブジェクトにファイル参照ツールの nameを含めます。ファイル参照ツールの名前がわからない場合は、 /v1/workflows/{appId}/questionsエンドポイントを使用してファイル参照ツールの名前を取得します。
valueは、入力ファイルの呼び出しが応答で返した参照IDです。

curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \
--header 'Content-Type: text/plain' \
--header 'Authorization: OAuth oauth_consumer_key="{consumer key}",
                         oauth_signature_method="HMAC-SHA1",
                         oauth_timestamp="{timestamp}",
                         oauth_nonce="{nonce}",
                         oauth_signature="{signature}"' \
--data-raw '{
    "questions": [
        {
            "name": "File Browse",
            "value": "{reference ID}"
        }
    ]
    "priority": "Low"
}'

移行可能なエンドポイント

migratableエンドポイントを使用して、Server環境間でワークフローを移行します。これを利用して、開発およびテスト段階にあるワークフローのデプロイを管理することができます。

最初に、ワークフローを移行できるようにする必要があります。ワークフローに移行対象のマークを付けたら、以下の手順に従い、移行元の環境から移行先の環境の適切なサブスクリプション (スタジオ) に公開します。

ステップ 1.移行準備が整ったワークフローのリストを取得する

次に、次のエンドポイントを使用して、移行準備が整ったワークフローのリストを取得します。

環境: 移行元
方法: GET
エンドポイント: api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/

クエリパラメーターとして、 subscriptionIdsのカンマ区切りリストを含めます。サブスクリプション ID は、特定のスタジオを識別します。

指定されたサブスクリプション(スタジオ)下で移行準備完了とマークされた一連のワークフローが返されます。 subscriptionsIdsを指定しない場合、移行準備完了としてマークされたすべてのワークフローが返されます。この戻り値には、 appId、現在公開されている revisionId、ワークフローが属する subscriptionIDの3つのプロパティが含まれます。

ステップ 2.ソース環境からワークフローをダウンロードする

次のエンドポイントは、ワークフローをYXZPファイルとしてダウンロードします。

環境: 移行元
方法: GET
エンドポイント: api/admin/v1/{appID}/package/

パスパラメーターとして appIDを含めます。ワークフロー全体をパッケージとしたダウンロードが返されます。

ステップ 3.移行先の環境でワークフローを公開する

以下のエンドポイントは、ダウンロードしたワークフローを移行先の環境に公開します。

環境: 移行先
方法: POST
エンドポイント: api/admin/v1/workflows/

パラメーター
パラメータ	説明	型	必須
`file`	新しいワークフローのファイル名です。	文字列	True
`name`	新しいワークフロー名です。	文字列	True
`owner`	移行されたワークフローの所有者です。E メールアドレスは、移行先の環境に存在している必要があります。	文字列	True
`validate`	移行先の環境への移行時にワークフローを検証するためのフラグです。	ブール値	True
`isPublic`	ワークフローを公開に設定し、移行先の環境で「自社の Gallery」に表示させるためのフラグです。	ブール値	True
`sourceId`	移行されるワークフローの移行元環境の appId です。同じsourceIdを持つワークフローが存在する場合、移行先の環境でそのワークフローを置き換えます。それ以外の場合は、新しいワークフローが生成されます。 (appIDを指定しない場合は、空の文字列を送信します。)	文字列	True
`workerTag`	ワークフローにワーカータグを追加し、特定のワーカーがワークフローを実行するようにします。 (ワーカーを指定しない場合は、空の文字列を送信します。)	文字列	True
`canDownload`	移行先の環境の他のユーザーがワークフローをダウンロードできるように設定するフラグです。	ブール値	True

(オプション) ステップ 4.移行元の環境で移行設定のワークフローをリセットする

必要に応じて、 migratableエンドポイントを使用し、移行先の環境でワークフローを移行した後に、移行先の環境におけるワークフローの [ このワークフローを移行対象にする ] 設定を [ いいえ ] に戻すことができます。

環境: 移行元
方法: PUT
エンドポイント: api/admin/v1/workflows/migratable/{appID}/

Server API V3 エンドポイントとパラメーターの詳細については、「 Alteryx Server API V3 」のヘルプページを参照してください。

このセクションの内容: