REST API の基本（URL・クエリパラメータ・ページング）

この章の結論

• URL は https://<ホスト>/fscmRestApi/resources/11.13.18.05/<リソース> の形です。HCM は hcmRestApi、CX は crmRestApi と、製品ごとにコンテキスト・ルートが分かれます。
• 使えるリソースと属性は、製品別の REST API ドキュメントと、各リソースの describe で調べます。
• 一覧取得では limit・offset・orderBy を必ず指定 し、応答の hasMore が false になるまで繰り返します。limit の既定は 25 件、1 回に返るのは最大 500 件です。
• q の書き方は REST Framework Version で変わります。既定の Version 1 と Version 2 以降で構文が違う点に注意します。

全体像

URL の構造

https://<your-pod>.fa.<region>.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices/300100001/child/invoiceLines

上の URL は、ホスト → コンテキスト・ルート（fscmRestApi）→ resources → バージョン → リソース（invoices）→ キー → 子リソース、の順に並んでいます。

部分	内容	例
ホスト	環境の REST サーバー URL（環境の案内メールに記載）	https://<your-pod>.fa.<region>.oraclecloud.com
コンテキスト・ルート	製品群ごとのルート	fscmRestApi（ERP・SCM）、hcmRestApi（HCM）、crmRestApi（CX）
バージョン	API のバージョン。公式の推奨は 11.13.18.05	省略すると 404
リソース	業務オブジェクト	invoices（AP 請求書）、erpintegrations、currencyRates
キーと子リソース	1 件の指定と、その配下のデータ	/invoices/{InvoiceId}/child/invoiceLines

• 公式ドキュメントの例では、ERP の請求書は /fscmRestApi/resources/11.13.18.05/invoices、HCM の従業員は /hcmRestApi/resources/11.13.18.05/workers、CX の取引先は /crmRestApi/resources/11.13.18.05/accounts です。
• 26D 時点では、/api/boss/data/objects/<モジュール>/v1/<サービス名> 形式の新しいリソース（ドキュメント上の呼称は Spectra）もあります。クエリパラメータの書き方（$filter・$limit など）や認証（OAuth 必須）が異なるため、このページでは従来の 11.13.18.05 形式を扱います。

リソースの調べ方

1. 製品別の REST API ドキュメントを見る：「REST API for Oracle Fusion Cloud Financials」などのガイドの All REST Endpoints に、リソース・操作・属性・finder の一覧があります。
2. describe で実環境のメタデータを見る：属性の型、必須（mandatory）、更新可否（updatable）、検索可否（queryable）、子リソース、アクション、値リスト（LOV）が分かります。環境ごとに定義が異なる項目（DFF など）を確認するときも describe を使います。
3. finder を確認する：各リソースの「Get all」操作の説明に、使える finder 名と変数が載っています。

用途	URL
1 リソースのメタデータ	/fscmRestApi/resources/11.13.18.05/invoices/describe
全リソースの URL 一覧	/fscmRestApi/resources/11.13.18.05/describe?metadataMode=list
全リソースの簡易メタデータ	/fscmRestApi/resources/11.13.18.05/describe?metadataMode=minimal

• Accept: application/vnd.oracle.openapi3+json を付けると、OpenAPI 形式で取得できます。
• Accept-Language を付けると、表示ラベル（title など）がその言語で返ります。

HTTP メソッド

メソッド	単一リソース	コレクション	用途
GET	〇	〇	1 件取得／一覧取得
POST	－	〇	新規作成、カスタム・アクションの実行
PATCH	〇	－	指定した項目だけ更新
DELETE	〇	－	削除

• POST・PATCH の本文の Content-Type は application/vnd.oracle.adf.resourceitem+json です（application/json を受け付けるリソースもあります）。
• 子リソースは、通常は親リソースのセキュリティ権限を引き継ぎます。
• 作成・更新・削除は REST API 応用 で扱います。

クエリパラメータ

一覧

パラメータ	用途	例	既定値・注意
q	行の絞り込み	q=InvoiceAmount > 100000	queryable な属性のみ。構文は Framework Version で変わる
finder	定義済み検索	finder=PrimaryKey;InvoiceId=300100001	形式は 名前;変数=値,変数=値
fields	返す属性の限定	fields=InvoiceId,InvoiceNumber	子は ;子:属性 で指定
expand	子リソースの埋め込み	expand=invoiceLines	既定は埋め込まない。all で全部
onlyData	links を省く	onlyData=true	既定は false（links 付き）
limit	1 回の件数	limit=100	既定 25。1 回に返るのは最大 500 件
offset	開始位置	offset=100	既定 0（0 始まり）
totalResults	総件数を返す	totalResults=true	既定 false
orderBy	並べ替え	orderBy=InvoiceDate:desc,InvoiceId	既定は昇順。並びは大文字小文字を区別

• fields と expand を組み合わせると、親と子の必要な属性だけを 1 回で取れます：fields=InvoiceId,InvoiceNumber;invoiceLines:LineNumber,LineAmount
• 存在しない属性や、queryable でない属性を q に使うと 400 Bad Request になります。

q の書き方（Framework Version 1 と 2 以降）

REST Framework Version は、要求ヘッダー REST-Framework-Version で指定します。省略時は Version 1 です。

Version	構文	例
1（既定）	検索例（Query by Example）形式。条件を ; で区切ると AND。子リソースでの絞り込みは不可	q=InvoiceAmount>=100000;PaidStatus=Unpaid
2 以降	式の形式。and・or・括弧、IN・BETWEEN・UPPER()、子リソースの属性で絞り込み可	q=InvoiceAmount >= 100000 and PaidStatus = 'Unpaid'

Version 2 以降では、Version 1 の ; 区切りの書き方はエラーになります。Version 2 以降で使える主な演算子は次のとおりです。

データ型	主な演算子
文字列	=、<>、LIKE（% は Version 2 以降）、UPPER(属性) LIKE、IN、NOT IN、IS NULL、IS NOT NULL
数値	=、<>、<、<=、>、>=、BETWEEN、NOT BETWEEN、IN、NOT IN
日付・日時	比較演算子、BETWEEN、NOT BETWEEN、IS NULL
真偽値	= 'true'、= 'false'、= 'Y'、= 'N' など

q=Supplier IN ('サンプル商事株式会社', 'テスト物産株式会社')
q=InvoiceDate BETWEEN '2026-10-01' AND '2026-10-31'
q=UPPER(Description) LIKE '%RENT%'
q=invoiceLines.LineType = 'Freight'        （子リソースの属性で親を絞る。Version 2 以降）

Version 9 では、LIKE の中で \ を使ってワイルドカード（% など）をエスケープできます。

ページング

一覧の応答は、次の形で返ります。

{
  "items": [ { "InvoiceId": 300100001, "InvoiceNumber": "SMP-0001" } ],
  "count": 25,
  "hasMore": true,
  "limit": 25,
  "offset": 0,
  "links": [ { "rel": "self", "href": "https://.../invoices", "name": "invoices", "kind": "collection" } ]
}

項目	意味
items	今回返ったデータ
count	今回返った件数
hasMore	まだ続きがあれば true、最後なら false
limit・offset	今回の取得条件
totalResults	総件数（totalResults=true のときだけ返る）

全件取得の手順は次のとおりです。

1. limit（例：500）と、一意な属性での orderBy（例：InvoiceId）を付けて 1 回目を取得する
2. offset に、それまでの合計件数を足して次を取得する
3. hasMore が false になったら終了する

• orderBy がないと、ページ間の並び順は保証されません。また、取得中にデータが増減すると、ページの境目がずれて重複や漏れが起きます。
• 大量・長時間の取得では、一意キーで並べて「前ページの最後のキーより大きいもの」を q で指定する方法（キーセット方式。例：orderBy=InvoiceId&q=InvoiceId > 300100500）も有効です。公式の並べ替えの説明にも orderBy=OptyId&q=OptyId>1000 という形の例があります。
• 数万件を超える抽出は REST ではなく BICC などを検討します（連携方式の全体像）。

日付・数値の形式

型	形式	例
日付（string (date)）	ISO 8601 の日付文字列	"2026-10-01"
日時（string (date-time)）	ISO 8601 の日時文字列	"2026-10-01T09:30:00+00:00"
数値（number・integer）	JSON の数値	123456.78
真偽値	true／false	true
長いテキスト（CLOB）	文字列	Version 8 以降は Base64 ではなく文字列のまま

• q の日時は UTC 形式（例：'2026-10-01T00:00:00Z'）とローカル形式の両方を受け付けます。属性ごとのタイムゾーンの扱いは、実データで確認してから条件を組みます。
• Version 9 では、桁数の大きい数値が丸めを防ぐために文字列で返ります。金額は、受け取る側でも浮動小数点ではなく 10 進数型（Python なら Decimal）で扱います。
• URL に空白や引用符を含めるときは URL エンコードが必要です。curl では -G と --data-urlencode を使うと安全です。

コード例

実機の例

実機：describe・一覧・絞り込み

export FA_HOST="https://<your-pod>.fa.<region>.oraclecloud.com"
export API="$FA_HOST/fscmRestApi/resources/11.13.18.05"
# FA_USER / FA_PASS は環境変数に設定済みとする

# 1) 属性の一覧（queryable・mandatory を確認）
curl -s -u "$FA_USER:$FA_PASS" "$API/invoices/describe" | head -c 2000

# 2) 未払いの高額請求書を、必要な項目だけ・新しい順に 50 件
curl -s -G -u "$FA_USER:$FA_PASS" "$API/invoices" \
  -H "REST-Framework-Version: 4" \
  --data-urlencode "q=InvoiceAmount >= 100000 and PaidStatus = 'Unpaid'" \
  --data-urlencode "fields=InvoiceId,InvoiceNumber,Supplier,InvoiceAmount,InvoiceDate" \
  --data-urlencode "orderBy=InvoiceDate:desc,InvoiceId" \
  --data-urlencode "limit=50" \
  --data-urlencode "onlyData=true"

# 3) finder で主キー検索
curl -s -G -u "$FA_USER:$FA_PASS" "$API/invoices" \
  --data-urlencode "finder=PrimaryKey;InvoiceId=300100001" \
  --data-urlencode "onlyData=true"

モック API の例

このサイトの練習用モック API（プレイグラウンド）でも同じ形で試せます。モックは本物の Oracle API ではなく、データは架空です。

モック API：Version 1 と Version 2 の q の違い

export BASE="https://<このサイトのURL>/api/mock/fscmRestApi/resources/11.13.18.05"

# Version 1（既定）：; 区切りで AND
curl -s -G -u learner:welcome1 "$BASE/invoices" \
  --data-urlencode "q=InvoiceAmount>100000;PaidStatus=Unpaid" \
  --data-urlencode "fields=InvoiceId,InvoiceNumber,InvoiceAmount,PaidStatus" \
  --data-urlencode "onlyData=true"

# Version 2：and / or / 括弧が使える
curl -s -G -u learner:welcome1 "$BASE/invoices" \
  -H "REST-Framework-Version: 2" \
  --data-urlencode "q=InvoiceAmount >= 100000 and (PaidStatus = 'Unpaid' or PaidStatus = 'Partially paid')" \
  --data-urlencode "orderBy=InvoiceAmount:desc" \
  --data-urlencode "onlyData=true"

# ページング：totalResults と hasMore を確認
curl -s -u learner:welcome1 "$BASE/invoices?limit=10&offset=20&totalResults=true&onlyData=true&orderBy=InvoiceId"

# 親子をまとめて取得
curl -s -G -u learner:welcome1 "$BASE/invoices" \
  --data-urlencode "fields=InvoiceId,InvoiceNumber;invoiceLines:LineNumber,LineAmount" \
  --data-urlencode "expand=invoiceLines" \
  --data-urlencode "limit=2" --data-urlencode "onlyData=true"

全件取得の最小例（Python）

fetch_all.py：hasMore が false になるまで取得する

import os
import requests

BASE = os.environ["BASE"]  # 実機なら https://<host>/fscmRestApi/resources/11.13.18.05
AUTH = (os.environ.get("FA_USER", "learner"), os.environ.get("FA_PASS", "welcome1"))

def fetch_all(resource: str, page_size: int = 500, **params) -> list[dict]:
    rows, offset = [], 0
    while True:
        query = {"limit": page_size, "offset": offset, "onlyData": "true", **params}
        r = requests.get(f"{BASE}/{resource}", params=query, auth=AUTH, timeout=60)
        r.raise_for_status()
        body = r.json()
        rows.extend(body["items"])
        if not body.get("hasMore"):
            return rows
        offset += body["count"]

invoices = fetch_all("invoices", orderBy="InvoiceId",
                     fields="InvoiceId,InvoiceNumber,InvoiceAmount")
print(len(invoices))

再試行・タイムアウト・トークン更新を加えた実践版は REST 演習3 で作ります。

落とし穴とベストプラクティス

よくあるミス

• limit を付けずに「全件取れた」と思い込む：既定は 25 件です。hasMore を必ず確認します。
• orderBy なしでページングする：ページの境目で重複や漏れが起きます。一意な属性で並べます。
• Framework Version と q の構文が合っていない：ヘッダーなし（Version 1）で and や IN を使う、Version 2 以降で ; 区切りを使う、のどちらも典型的な 400 の原因です。
• URL エンコードを忘れる：q の空白・引用符・% が崩れて、意図しない条件や 400 になります。
• expand=all を常用する：不要な子まで取得して遅くなります。fields で必要な子と属性だけにします。

• 必要な項目だけ取る：fields と onlyData=true で応答を小さくします（公式の Integration Playbook も推奨しています）。
• 検索条件は queryable を確認してから書く：describe で確認できます。
• 環境固有の項目は describe で確認する：DFF などは環境ごとに定義が異なります。

試験対策ポイント

• 対応する試験：OIC 模擬テスト（ERP Cloud アダプタや REST アダプタで Fusion の REST リソースを呼ぶ場面）
• 覚えるポイント
  • URL の構成要素（コンテキスト・ルート、resources、バージョン 11.13.18.05、リソース、/child/）
  • q・finder・fields・expand・onlyData・limit・offset・totalResults・orderBy の役割
  • hasMore によるページングと、limit の既定 25 件
  • Framework Version 1 と 2 以降で q の構文が変わること
• 手を動かして確認：REST 演習1：請求書を検索・絞り込みする

公式ドキュメント

• Quick Start（REST API for Oracle Fusion Cloud Financials 26D）
• REST API Versions and URL Paths
• Manage Collections（q・finder・ページング・並べ替え）
• Supported HTTP Methods（クエリパラメータの既定値）
• Supported Data Types
• Access Metadata（describe）
• Set the REST Framework Version
• REST APIs（Integration Playbooks for Procurement 26D）

関連ページ

• REST API 応用（子リソース・作成更新・フレームワークバージョン・エラー）
• 認証・認可（Basic・OAuth・JWT・統合ユーザー）
• REST API・ESS チートシート
• 練習用 API プレイグラウンド
• REST 演習3：Python でページングしながら全件取得する