取得¶
GET /api/v1/workspace/declaration/get
概要¶
現在のワークスペース属性クレームを読み取り、必要に応じて組織情報のバックグラウンド同期をトリガーします。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。ワークスペースは Key によって決定されるため、Query または Body で workspaceUUID を別途渡すことはできません。ワークスペースクレームは業務識別子と返却表示に使用するキー/値設定であり、データアクセス認可、課金組織の移行、リソース名変更のためのインターフェースではありません。
content のトップレベルにあるクレームキーを読み取ります。空でないオブジェクトには、共通 OpenAPI レスポンスによって content.declaration(呼び出し対象ワークスペースのキャッシュ内にある共通クレーム)が追加されます。これは本ページで新たに追加された別階層の業務オブジェクトではありません。レスポンス全体の外殻やこの補助フィールドをそのまま書き戻さないでください。過去の設定で declaration と同名のキーを独自に使用している場合、その元の値が返される可能性があります。カスタムキーは declaration/organization/business/data/pageInfo などの予約された意味を避けることを推奨します。過去のカスタムフィールドに data と pageInfo が同時に含まれる場合、共通ラッパーは pageInfo をレスポンスのトップレベルへ移動します。これは API のページネーションを意味せず、移動されたフィールドを破棄して盲目的に書き戻すこともできません。空のクレームでは {} が返されることがあり、過去の非課金設定では null になることもあります。business や organization が常に存在する保証はありません。
pay/enterprise ワークスペースでは組織情報をリアルタイムで補完しようとし、失敗した場合は保存値をそのまま使用する可能性があります。差異がある場合はバックグラウンド同期もトリガーされるため、この GET は完全に副作用がないわけではありません。バックグラウンド同期は、今回のレスポンスでタスク ID や完了進捗を提供しません。非同期キューが利用できない場合も、読み取りが 500 になる可能性があります。その他のバージョンでは保存済みクレームを直接返し、同じ補完が実行される保証はありません。業務文字列の表示は実際の返却値に従って読み取る必要があり、business を固定の配列として扱わないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得してください。 |
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/workspace/declaration/get' \
-H 'DF-API-KEY: <DF-API-KEY>'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object または null | クレームのキー/値オブジェクト。空の設定では {} になる場合があり、一部の過去の非課金レコードでは null になる場合があります。 |
| content.organization | string または null | システムが管理する組織識別子。省略可能。有料/エンタープライズ版では組織情報から取得します。デプロイメントプランでは変更時に default_private_organization として保存されます。ワークスペース UUID とは異なり、本 API で対象組織を指定することはできません。 |
| content.business | 任意の過去 JSON 値 | 業務属性。省略可能。pay/enterprise の読み取りおよび現在の変更では文字列に正規化されます。非課金の GET では過去の配列/null などをそのまま返す場合があるため、常に string として解析しないでください。 |
| content.{カスタムキー} | 任意の過去 JSON 値 | ユーザー定義キー。実際のキーに従って読み取ります。現在の変更では非文字列値が JSON 文字列に変換されますが、過去に保存された値は他の型のままである可能性があります。 |
| pageInfo | 任意の過去 JSON 値 | クレームに元々 data/pageInfo が同時に含まれる場合に限り、共通ラッパーによってトップレベルへ移動されます。本 API のページネーションではありません。 |
| content.declaration | object または null、または過去のカスタム値 | 空でないオブジェクトに追加される可能性がある共通クレーム。トップレベルで読み取るソース/更新時刻とは異なる場合があります。同名のカスタムフィールドを保持する場合は上書きしません。 |
{
"code": 200,
"content": {
"organization": "organization_example",
"business": "checkout",
"costCenter": "platform",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては、共通エラー定義を参照してください。
共通の認証、ホワイトリスト、レート制限エラーについては、共通エラー定義を参照してください。リアルタイムの組織情報読み取りで例外が発生した場合は、まず保存値へフォールバックします。組織のアップストリームエラーを毎回この API の失敗と同一視しないでください。後続の非同期配信で例外が発生した場合は、引き続き 500 が発生する可能性があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 401 | ft.WKSPNotExistOrReleased | API Key が示すワークスペースに有効なレコードがない、または解放済み | ワークスペースが存在しない/または解放済み | Key の所属とワークスペースの状態を確認してください。 |
| 500 | ft.InternalServerError | クレームの保存形式が非互換、読み取り失敗、または非同期同期タスクの配信失敗 | 内部エラー | traceId を保持して管理者に連絡し、後で読み取ってください。今回の結果からバックグラウンドタスクが完了したと推測しないでください。 |