API リクエストの構造

API リクエストは正確な仕様に従って作成する必要があります。Anaplan Financial Consolidation では、これらは HTTP 動詞 (メソッドとも呼ばれます)、ルート URL、API バージョン、API エンドポイント、クエリ パラメーター、ヘッダー、リクエスト本文で構成されています。

たとえば、GET https://fluenceapi-prod.fluence.app//api/v2305.1/odata/ClientSchemaTable のようになります。こちらの説明は以下のとおりです。

• GET は HTTP 動詞/メソッドです。
• https://fluenceapi-prod.fluence.app はルート URL です。
• /api/v2305.1 は API バージョン パラメーターです。
• /odata/ClientSchemaTable はエンドポイントかリソース パスであり、その後にクライアント スキーマ テーブルの名前が続きます。

API リクエストには、ヘッダー データと本文データも含まれる場合があります。

HTTP メソッドは RESTful API リクエストに不可欠です。API では、GET、POST、PUT、DELETE などの一般的なメソッドを使用します。これらのメソッドを使用すると、Financial Consolidation API への API リクエストを通じてデータを取得、追加、更新、削除できます。

ホスト名 (ルート URL とも呼ばれます) は、HTTP 経由でアクセス可能なオブジェクト又はデータ オブジェクトのグループを表す一意の URL です。Financial Consolidation API リクエストには独自のルート URL があり、HTTP クライアントはそこにルーティングされてデータ リソースを操作します。

Anaplan Financial Consolidation の API リクエストでは、有効なリクエストの一部として、ルート URL の直後に現在の /api API バージョンを宣言する必要があります。API の現在のバージョンは 2305.1 です。

リソース パスとは、特定のリソース又はリソースのコレクションを識別して見つける API のエンドポイント URL の部分を指します。これは通常、API のデータ モデル内のリソースの場所を階層的に表現したものです。
リソース パスは、スラッシュ (/) で区切られた一つ以上のパス セグメントで構成されています。各パス セグメントには、英数字のほか、ハイフン (-) やアンダースコア (_) などの特定の特殊文字を含めることができます。パス セグメントは API のリソース階層を移動し、ターゲット リソースを識別します。

以下の例では、リクエストのエンドポイントは /odata になります。

GET https://fluenceapi-prod.fluence.app/api/v2305.1/odata

Anaplan Financial Consolidation では現在次のエンドポイントをサポートしています。

クエリ パラメーターは、フィルタリング、並べ替え、及び API リクエストによる特定のデータの取得の許可の基準として機能します。クエリ パラメーター内で論理演算子を使用できます。

API クエリ パラメーターは、URL 内の疑問符の後に表示されるオプションのキーと値のペアです。これらは URL 拡張子として機能し、配信されたデータに基づいて特定のコンテンツやアクションを決定するのに役立ちます。クエリ パラメーターを追加するには、リクエスト URL の末尾に「?」を使用し、その後にパラメーター名と値を続けます。

たとえば、テーブルからデータを取得するときに、クエリ パラメーターを使用して結果をフィルタリングできます。

複数のクエリ パラメーターをアンパサンド (&) で区切って追加し、クエリ文字列を形成できます。クエリ パラメーターは、文字列や数値など、長さが異なるさまざまなオブジェクト タイプに対応できます。

クエリ パラメーターの詳細を参照してください。

一部のエンドポイント パスには、リクエストを形成するために段階的に構築するパラメーターのチェーンが含まれています。[?Page] パラメーターを使用して、取得するクエリ ページを指定します。[?PageSize] を使用して、ページで取得する行数を指定します。 たとえば、ディメンション メタデータとその基礎となるプロパティを取得するには、次のようなものを使用します: https://fluenceapi-prod.fluence.app/api/v2305.1/metadata/Dimensions/DataView?Page=1&PageSize=100

リクエスト ヘッダーには、認証トークンや勘定テナントなどの要素を表す情報が含まれています。REST ヘッダーでは、リクエストとレスポンスのデータ形式を指定し、リクエストのステータスに関する情報も提供します。

例:

上記の例では以下の三つのヘッダーがあります。

• Tenant: データが保存されるテナント。
• Content-Type: リクエスト本文で送信されるデータ形式。このケースでは、本文の内容が JSON 形式であることを指定しています。
• X_API_TOKEN: 管理者が API キーの形式で作成した有効な API トークンの値。

これらのヘッダーはサーバーに重要な情報を提供し、サーバーがリクエストを正しく安全に処理できるようにします。

API リクエストは、通常 POST 及び PUT HTTP メソッドで機能するデータ (「本文」と呼ばれる) で構成されています。本文データは、リクエストとともに送信されるペイロード又はコンテンツを指します。JSON や CSV データなど、処理のためにサーバーに送信する必要があるデータが含まれています。

たとえば、クライアント テーブルにレコードを追加するには、本体にレコード内のすべてのアイテムが含まれている必要があります。

上記の例では、リクエストは、「Consolidation」クライアント スキーマ テーブル内に予算データの新しい行を作成するための POST メソッドです。本文データは JSON 形式で表され、レコードに関する情報が含まれています。このケースでは、本文データは、Account、Audit、CostCenter、Currency、DataView、Date、Entity、Intercompany、Movement、Product、Scenario、Measure、Amount、text、Periodic_Amount の交差のどのメンバーがテーブルに新しい行を作成するために使用されるかを反映しています。

すべての API リクエストに本文が必要なわけではないことに忘れないことが重要です。たとえば、GET リクエストはサーバーにデータを送信するのではなく、サーバーからデータを取得するため、通常は本文がありません。ただし、POST や PUT などのメソッドでは、作成または更新の目的でデータを送信するための本体が必要になることがよくあります。

API レスポンスは、クライアントのリクエストに対するサーバーの応答です。クライアントがリクエストしたデータか情報が含まれています。レスポンスは通常、HTTP レスポンスの本文でクライアントに送り返されます。レスポンス ペイロードは実用的なものであれば何でも構いません。

レスポンスには次の要素が含まれています。

• Status: リクエストのステータスを表示します。「success」か「error」のいずれかになります。
• Code: リクエストの成功または失敗を表す数値のステータス コードを表示します。
• Data: API によって返される実際のデータが含まれています。データ レスポンスは通常、JSON 形式です。

Financial Consolidation API リクエストでは、2XX、4XX、5XX の各カテゴリーで HTTP レスポンスを返します。

• 2XX レスポンスは API 呼び出しが成功したことを示しています。
• 4XX レスポンスはリクエストに問題があることを示しています。  必須のリクエスト パラメーターを確認します。次に、リクエスト パラメーターと本文に必要な値とタイプが含まれているかどうかを確認します。エラーの診断に役立つエラー メッセージがレスポンス本文に含まれているはずです。
• 5XX レスポンスは、クライアントと API サーバー間の通信に問題があることを示しています。

以下の表は、Financial Consolidation API で予想される HTTP レスポンスをまとめたものです。