サンドボックス管理エンドポイント

Adobe Experience Platformのサンドボックスは、実稼動環境に影響を与えることなく機能のテスト、実験の実行、カスタム設定を可能にする、独立した開発環境を提供します。 Sandbox API の /sandboxes エンドポイントを使用すると、Platform のサンドボックスをプログラムで管理できます。

はじめに

このガイドで使用する API エンドポイントは、Sandbox API の一部です。先に進む前に、はじめる前にを参照し、関連ドキュメントへのリンク、このドキュメントのサンプル API 呼び出しを読み取るためのガイドおよび任意の Experience Platform API を正常に呼び出すために必要なヘッダーに関する重要な情報を確認してください。

サンドボックスのリストの取得 list

/sandboxes エンドポイントに対してGETリクエストを行うことで、組織(アクティブかどうかにかかわらず)に属するすべてのサンドボックスをリストできます。

API 形式

GET /sandboxes?{QUERY_PARAMS}
パラメーター
説明
{QUERY_PARAMS}
結果をフィルタリングするオプションのクエリパラメーター。 詳しくは、 クエリパラメーターの節を参照してください。

リクエスト

curl -X GET \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes?&limit=4&offset=1 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

成功応答は、組織に属するサンドボックスのリスト(nametitlestatetype などの詳細を含むを返します。

{
    "sandboxes": [
        {
            "name": "prod",
            "title": "Production",
            "state": "active",
            "type": "production",
            "region": "VA7",
            "isDefault": true,
            "eTag": 2,
            "createdDate": "2019-09-04 04:57:24",
            "lastModifiedDate": "2019-09-04 04:57:24",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "dev",
            "title": "Development",
            "state": "active",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-03 22:27:48",
            "lastModifiedDate": "2019-09-03 22:27:48",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "stage",
            "title": "Staging",
            "state": "active",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-03 22:27:48",
            "lastModifiedDate": "2019-09-03 22:27:48",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        },
        {
            "name": "dev-2",
            "title": "Development 2",
            "state": "creating",
            "type": "development",
            "region": "VA7",
            "isDefault": false,
            "eTag": 1,
            "createdDate": "2019-09-07 10:16:02",
            "lastModifiedDate": "2019-09-07 10:16:02",
            "createdBy": "{USER_ID}",
            "modifiedBy": "{USER_ID}"
        }
    ],
    "_page": {
        "limit": 4,
        "count": 4
    },
    "_links": {
        "next": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes/?limit={limit}&offset={offset}",
            "templated": true
        },
        "prev": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=0&limit=1",
            "templated": null
        },
        "page": {
            "href": "https://platform.adobe.io:443/data/foundation/sandbox-management/sandboxes?offset=1&limit=1",
            "templated": null
        }
    }
}
プロパティ
説明
name
サンドボックスの名前。このプロパティは、API 呼び出しでルックアップに使用されます。
title
サンドボックスの表示名。
state

サンドボックスの現在の処理状態です。サンドボックスの状態は、次のいずれかになります。

  • creating: サンドボックスが作成されましたが、まだシステムによるプロビジョニングが行われています。
  • active:サンドボックスが作成され、アクティブになります。
  • failed: エラーが発生したので、サンドボックスをシステムでプロビジョニングできなかったため、無効になりました。
  • deleted:サンドボックスは手動で無効になりました。
type
サンドボックスタイプ。 現在サポートされているサンドボックスのタイプには、developmentproduction があります。
isDefault
このサンドボックスが組織のデフォルトの実稼動サンドボックスであるかどうかを示すブール値プロパティ。
eTag
サンドボックスの特定のバージョンの識別子。バージョン管理とキャッシュの効率化に使用され、この値はサンドボックスに変更が追加されるたびに更新されます。

サンドボックスの検索 lookup

個々のサンドボックスを検索するには、リクエストパスにサンドボックスの name プロパティを含む GET リクエストを作成する必要があります。

API 形式

GET /sandboxes/{SANDBOX_NAME}
パラメーター
説明
{SANDBOX_NAME}
検索するサンドボックスの name プロパティです。

リクエスト

次のリクエストは、「dev-2」という名前のサンドボックスを取得します。

curl -X GET \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/dev-2 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \

応答

成功した応答は、サンドボックスの詳細(nametitlestatetype)を返します。

{
    "name": "dev-2",
    "title": "Development 2",
    "state": "creating",
    "type": "development",
    "region": "VA7",
    "isDefault": false,
    "eTag": 1,
    "createdDate": "2019-09-07 10:16:02",
    "lastModifiedDate": "2019-09-07 10:16:02",
    "createdBy": "{USER_ID}",
    "modifiedBy": "{USER_ID}"
}
プロパティ
説明
name
サンドボックスの名前。このプロパティは、API 呼び出しでルックアップに使用されます。
title
サンドボックスの表示名。
state

サンドボックスの現在の処理状態。サンドボックスの状態は、次のいずれかになります。

  • 作成:サンドボックスは作成されましたが、システムによって引き続きプロビジョニングされています。
  • アクティブ:サンドボックスが作成され、アクティブです。
  • 失敗:エラーが原因で、サンドボックスはシステムでプロビジョニングできず、無効になっています。
  • 削除:サンドボックスは手動で無効にされています。
type
サンドボックスタイプ。 現在サポートされているサンドボックスのタイプには、developmentproduction があります。
isDefault
このサンドボックスが組織のデフォルトのサンドボックスであるかどうかを示すブール型のプロパティです。通常、これは実稼働用サンドボックスです。
eTag
サンドボックスの特定のバージョンの識別子。バージョン管理とキャッシュの効率化に使用され、この値はサンドボックスに変更が追加されるたびに更新されます。

サンドボックスの作成 create

NOTE
新しいサンドボックスが作成されたら、新しいサンドボックスの使用を開始する前に、まず Adobe Admin Console でその新しいサンドボックスを製品プロファイルに追加する必要があります。製品プロファイルにサンドボックスをプロビジョニングする方法について詳しくは、製品プロファイルの権限の管理に関するドキュメントを参照してください。

/sandboxes エンドポイントにサンドリクエストを行うことで、開発用または実稼動用の新しいPOSTを作成できます。

開発サンドボックスを作成

開発用サンドボックスを作成するには、リクエストペイロードで type 属性に値 development を指定する必要があります。

API 形式

POST /sandboxes

リクエスト

次のリクエストは、「acme-dev」という名前の新しい開発用サンドボックスを作成します。

curl -X POST \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "type": "development"
  }'
プロパティ
説明
name
今後のリクエストでサンドボックスにアクセスするために使用される識別子。この値は一意である必要があります。ベストプラクティスはできる限りわかりやすい値にすることです。この値には、スペースや特殊文字を含めることはできません。
title
Platform ユーザーインターフェイスでの表示用に使用される、わかりやすい名前。
type
作成するサンドボックスのタイプ。実稼動以外のサンドボックスの場合、この値は development にする必要があります。

応答

正常な応答は、新しく作成されたサンドボックスの詳細を返し、state が「作成中」であることを示します。

{
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "state": "creating",
    "type": "development",
    "region": "VA7"
}
NOTE
サンドボックスのプロビジョニングには約 30 秒かかり、その後、サンドボックスの state が「アクティブ」または「失敗」になります。

実稼動用サンドボックスの作成

実稼動用サンドボックスを作成するには、リクエストペイロードで type 属性に値 production を指定する必要があります。

API 形式

POST /sandboxes

リクエスト

次のリクエストは、「acme」という名前の新しい実稼動サンドボックスを作成します。

curl -X POST \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H `Accept: application/json` \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "acme",
    "title": "Acme Business Group",
    "type": "production"
}'
プロパティ
説明
name
今後のリクエストでサンドボックスにアクセスするために使用される識別子。この値は一意である必要があります。ベストプラクティスはできる限りわかりやすい値にすることです。この値には、スペースや特殊文字を含めることはできません。
title
Platform ユーザーインターフェイスでの表示用に使用される、わかりやすい名前。
type
作成するサンドボックスのタイプ。実稼動サンドボックスの場合、この値は production である必要があります。

応答

正常な応答は、新しく作成されたサンドボックスの詳細を返し、state が「作成中」であることを示します。

{
    "name": "acme",
    "title": "Acme Business Group",
    "state": "creating",
    "type": "production",
    "region": "VA7"
}
NOTE
サンドボックスのプロビジョニングには約 30 秒かかり、その後、サンドボックスの state が「アクティブ」または「失敗」になります。

サンドボックスの更新 put

リクエストパスにサンドボックスのnameを含む PATCH リクエストを作成し、リクエストペイロードで更新するプロパティを作成することで、サンドボックス内の 1 つ以上のフィールドを更新できます。

NOTE
現在、更新できるのはサンドボックスの title プロパティのみです。

API 形式

PATCH /sandboxes/{SANDBOX_NAME}
パラメーター
説明
{SANDBOX_NAME}
更新するサンドボックスのnameプロパティ。

リクエスト

次のリクエストは、「acme」という名前のサンドボックスの title プロパティを更新します。

curl -X PATCH \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "title": "Acme Business Group prod"
  }'

応答

成功した応答は、新しく更新されたサンドボックスの詳細を含む HTTP ステータス 200(OK)を返します。

{
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "active",
    "type": "production",
    "region": "VA7"
}

サンドボックスのリセット reset

サンドボックスには、デフォルト以外のすべてのリソースをサンドボックスから削除する「ファクトリリセット」機能があります。 サンドボックスをリセットするには、そのサンドボックスの name をリクエストパスに含む PUT リクエストを作成する必要があります。

API 形式

PUT /sandboxes/{SANDBOX_NAME}
パラメーター
説明
{SANDBOX_NAME}
リセットするサンドボックスの name プロパティです。
validationOnly
実際のリクエストを行わずに、サンドボックスのリセット操作に関するプリフライトチェックを実行できるオプションのパラメーター。 このパラメーターを validationOnly=true に設定すると、リセットしようとしているサンドボックスにAdobe Analytics、Adobe Audience Managerまたはセグメント共有のデータが含まれているかどうかを確認できます。

リクエスト

次のリクエストでは、「acme-dev」という名前のサンドボックスがリセットされます。

curl -X PUT \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme-dev?validationOnly=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "action": "reset"
  }'
プロパティ
説明
action
サンドボックスをリセットするには、このパラメーターをリクエストペイロードで値「reset」と共に指定する必要があります。

応答

NOTE
サンドボックスがリセットされると、システムでプロビジョニングされるまでに約 30 秒かかります。

正常な応答は、更新されたサンドボックスの詳細を返し、state が「リセット中」であることを示します。

{
    "id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
    "name": "acme-dev",
    "title": "Acme Business Group dev",
    "state": "resetting",
    "type": "development",
    "region": "VA7"
}

デフォルトの実稼動用サンドボックスとユーザー作成の実稼動用サンドボックスは、その中にホストされている ID グラフがAdobe Analyticsでも クロスデバイス分析(CDA)機能に使用されている場合や、その中にホストされている ID グラフがAdobe Audience Managerでも People Based Destinations (PBD)機能に使用されている場合は、リセットできません。

サンドボックスがリセットされない可能性のある例外のリストを以下に示します。

{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2074-400"
},
{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2075-400"
},
{
    "status": 400,
    "title": "Sandbox `{SANDBOX_NAME}` cannot be reset. The identity graph hosted in this sandbox is also being used by Adobe Audience Manager for the People Based Destinations (PBD) feature, as well by Adobe Analytics for the Cross Device Analytics (CDA) feature.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2076-400"
},
{
    "status": 400,
    "title": "Warning: Sandbox `{SANDBOX_NAME}` is used for bi-directional segment sharing with Adobe Audience Manager or Audience Core Service.",
    "type": "http://ns.adobe.com/aep/errors/SMS-2077-400"
}

リクエストに ignoreWarnings パラメーターを追加することで、Audience Manager または Audience Core Service との双方向のセグメント共有に使用される実稼動用サンドボックスのリセットに進むことができます。

API 形式

PUT /sandboxes/{SANDBOX_NAME}?ignoreWarnings=true
パラメーター
説明
{SANDBOX_NAME}
リセットするサンドボックスの name プロパティです。
ignoreWarnings
検証チェックをスキップし、Audience Manager または Audience Core Service との双方向のセグメント共有に使用される実稼動サンドボックスを強制的にリセットできるオプションのパラメーターです。 このパラメーターは、デフォルトの実稼動サンドボックスには適用できません。

リクエスト

次のリクエストでは、「acme」という名前の実稼動サンドボックスがリセットされます。

curl -X PUT \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json'
  -d '{
    "action": "reset"
  }'

応答

正常な応答は、更新されたサンドボックスの詳細を返し、state が「リセット中」であることを示します。

{
    "id": "d8184350-dbf5-11e9-875f-6bf1873fec16",
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "resetting",
    "type": "production",
    "region": "VA7"
}

サンドボックスの削除 delete

IMPORTANT
デフォルトの実稼動サンドボックスは削除できません。

サンドボックスを削除するには、リクエストパスにサンドボックスの name を含む DELETE リクエストを実行します。

NOTE
この API 呼び出しを行うと、サンドボックスの status プロパティが「削除済み」に更新され、アクティベートが解除されます。 サンドボックスが削除された後も、GET リクエストを使用して、その詳細を取得できます。

API 形式

DELETE /sandboxes/{SANDBOX_NAME}
パラメーター
説明
{SANDBOX_NAME}
削除するサンドボックスの name
validationOnly
実際のリクエストを行わずに、サンドボックスの削除操作に関するプリフライトチェックを実行できるオプションのパラメーター。 このパラメーターを validationOnly=true に設定すると、リセットしようとしているサンドボックスにAdobe Analytics、Adobe Audience Managerまたはセグメント共有のデータが含まれているかどうかを確認できます。
ignoreWarnings
検証チェックをスキップし、Audience Manager または Audience Core Service との双方向のセグメント共有に使用される、ユーザー作成の実稼動用サンドボックスを強制的に削除できるオプションのパラメーターです。 このパラメーターは、デフォルトの実稼動サンドボックスには適用できません。

リクエスト

次のリクエストでは、「acme」という名前の実稼動サンドボックスが削除されます。

curl -X DELETE \
  https://platform.adobe.io/data/foundation/sandbox-management/sandboxes/acme?ignoreWarnings=true \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}'

応答

リクエストが成功した場合は、サンドボックスの更新された情報が返され、サンドボックスの state が「deleted」になったことが示されます。

{
    "name": "acme",
    "title": "Acme Business Group prod",
    "state": "deleted",
    "type": "development",
    "region": "VA7"
}
recommendation-more-help
e243ad8f-a318-46b3-9930-159a80f82b42