REST API を使用して連絡先を削除する
学習の目的
この単元を完了すると、次のことができるようになります。
- REST API を使用して連絡先を一括削除する。
- 要求の削除要求のステータスを取得する。
- 連絡先の削除要求をトラブルシューティングする。
連絡先をより効率的に削除する
Marketing Cloud Engagement から 1 ～ 2 件の連絡先を削除するのはごく簡単ですが、5 件を超えると急に、単調さに耐えられなくなることがあります。そのため、要求バッチあたりの連絡先の制限は 100 万件ですが、100 万件の連絡先を手動で選択することはないでしょう。大量の連絡先を削除する必要がある場合 (かつ、連絡先の削除が最良の選択であると確信している場合)、Marketing Cloud Engagement には、そのための REST API リソースが複数用意されています。
連絡先の削除を有効化する
開始する前に、連絡先の削除を有効化する必要があります。手順を復習するには、前の単元を参照してください。また、次の例のように、アカウントの連絡禁止期間を configSettings リソースを使用して変更できます。
例: 連絡先の削除の連絡禁止期間を構成する
次の例では、値を 0 日間 (即時削除) に設定しています (値 -1 を使用)。
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete/configSettings
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"items" : [{
"settingKey" : "SuppressionRestoreUntilDays",
"value" : "-1"
}
]
REST API を使用して連絡先を削除する方法を選択する
アカウントで連絡先の削除が有効化されたので、3 つの異なる値 (連絡先 ID、連絡先キー、データエクステンション) のいずれかを使用して削除する連絡先を選択できます。それぞれをサンプルコードと一緒に詳しく見ていきましょう。
連絡先 ID
連絡先 ID 値を使用する連絡先の削除を選択する場合、次の例のように配列で値を渡す必要があります。
例: 連絡先 ID で連絡先を削除する
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=ids
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"values": [12345678, 12345679],
"DeleteOperationType": "ContactAndAttributes"
}
連絡先キー
ContactKey 値を使用する連絡先の削除を選択する場合、これらの値も配列で渡す必要があります。
例: 連絡先キーで連絡先を削除する
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=keys
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"values": [
"TEST_317-531-5555", "TEST_317-531-5556"
],
"DeleteOperationType": "ContactAndAttributes"
}
データエクステンション
特定のデータエクステンションに含まれるすべての連絡先の削除を選択することもできます。この操作では、すべての送信可能データエクステンションで、そのデータエクステンションに含まれる連絡先レコードが削除されます。これには、ContactKey、ContactID、およびメールアドレス値に基づいて送信するデータエクステンションが含まれます。完了時にデータエクステンション全体を削除するかどうかも決定できます。選択するものが沢山あります!
このプロセスでは、削除要求のバッチへの非同期要求が作成されます。アカウントでの削除要求制限の構成方法についての詳細は、Marketing Cloud Engagement アカウントマネージャーにお問い合わせください。
データエクステンションを削除することを指定して、そのデータエクステンションの外部キーを含める必要があります。また、同期済みデータエクステンションを削除することはできません。これらを使用して削除する連絡先を識別することはできますが、実際のデータエクステンションは存続します。
例: データエクステンションを使用して連絡先を削除する
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=listReference
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"deleteOperationType": "ContactAndAttributes",
"targetList": {
"listType": {
"listTypeID": 3
},
"listKey": "ContactListDeleteSource_as_DataExtension"
},
"deleteListWhenCompleted": false,
"deleteListContentsWhenCompleted": false
}
要求を確認する
すでに述べたとおり、連絡先の削除要求は完了までに少し時間がかかります。実際には、要求に含まれる連絡先の数、実行する要求の数、その他のシステム要因に応じて数時間かかることもあります。ただし、OperationID 値を使用することで、要求について最新の進行状況を把握できます。各連絡先の削除要求は OperationID 値を返します。この値を使用して使用可能な情報を取得できます。要求の例として次のようなものがあります。
例: 特定の連絡先の削除要求のステータスを取得する
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com GET /contacts/v1/contacts/actions/delete/status?operationID=IDVALUEHERE Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN
次の応答例には、削除された連絡先の情報が表示されています。
{
"operation": {
"listTypeID": 3,
"listIdentifier": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
"listKey": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
"expectedListCount": 1,
"deleteType": "ContactAndAttributes",
"deleteListOnCompleted": false,
"operationID": 2,
"eID": 12345,
"mID": 12345,
"employeeID": 30980,
"operationRequestID": "21d0d10d-a15a-413c-bc3e-8b43b185e551",
"status": "Completed",
"scheduledTime": "2016-06-14T16:01:58.107",
"retryCount": 0,
"createdDate": "2016-06-14T16:02:00",
"createdBy": 30980,
"modifiedDate": "2016-06-14T16:02:00",
"modifiedBy": 30980
},
"requestServiceMessageID": "93631be1-107f-4239-a8b7-cdae245d7403",
"resultMessages": [],
"serviceMessageID": "00e6add8-d79a-4bd6-9568-2f2a272538f0"
}
例: 日付で連絡先の削除要求を取得する
指定された日付範囲内に実行された要求のサマリーを取得することもできます。
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests?startdateutc=2019-02-18T00%3A00%3A00&enddateutc=2019-03-19T00%3A00%3A00&%24page=1&%24pagesize=20&%24orderby=operationId%20desc&statusid=5
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
応答には、該当する要求すべてについて OperationID 値と短いサマリーが含まれます。より具体的な情報は、/contacts/v1/contacts/actions/delete/status?operationID= リソースで OperationID を使用します。
"startDateUtc":"2019-02-18T00:00:00",
"endDateUtc":"2019-03-19T00:00:00",
"statusAsOfDateUtc":"2019-03-19T19:33:17.496471Z",
"pageNumber":1,
"pageSize":20,
"operations":[
{
"operationId":22944,
"totalContactCount":1,
"completedContactCount":1,
"receivedDateUtc":"2019-03-04T22:42:00",
"status":"Completed",
"lastStatusDateUtc":"2019-03-19T04:47:40.293",
"deleteMethod":"Contact Key/ID"
},
{
"operationId":22943,
"totalContactCount":1,
"completedContactCount":1,
"receivedDateUtc":"2019-03-04T22:41:00",
"status":"Completed",
"lastStatusDateUtc":"2019-03-19T04:47:40.293",
"deleteMethod":"Contact Key/ID"
},
{
"operationId":22625,
"totalContactCount":1,
"completedContactCount":1,
"receivedDateUtc":"2019-02-26T23:26:00",
"status":"Completed",
"lastStatusDateUtc":"2019-03-13T10:10:17.9",
"deleteMethod":"Contact Key/ID"
}
],
"requestServiceMessageID":"e1198208-6432-40fd-b5ae-172c9d9bc44a",
"responseDateTime":"2019-03-19T13:33:18.2141124-06:00",
"resultMessages":[],
"serviceMessageID":"ef7d833c-509f-4dbc-8f99-060aac3c0382"
}
例: 連絡先の削除要求のサマリーを取得する
次の例では、指定された期間のすべての要求についてステータスレポートのサマリーが表示されます。
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com GET contacts/v1/contacts/analytics/deleterequests/summary?startdateutc=2018-01-15T00:00:00Z&enddateutc=2018-01-15T05:00:00Z Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN
応答例には、要求の completed (完了)、processing (処理中)、invalid (無効) の内訳が表示されています。
{
"startdateutc":"2018-01-15T00:00:00Z",
"enddateutc":"2018-01-15T04:30:00Z",
"statusofdateutc": "2018-01-17T04:30:00Z",
"interval":"0",
"itemcount":5,
"totaltimeseries":[
{
"requestcount":500,
"minvalue":100,
"maxvalue":100,
"items":[
{time:"01-15-2018 00:00:00","value":100},
{time:"01-15-2018 01:00:00","value":100},
{time:"01-15-2018 02:00:00","value":100},
{time:"01-15-2018 03:0000:","value":100},
{time:"01-15-2018 04:00:00","value":100}
]
}],
"statustimeseries":[
{
"statusid": 5,
"status": "Completed",
"requestcount":350,
"minvalue":0,
"maxvalue":100,
"items":[
{time:"01-15-2018 00:00:00","value":100},
{time:"01-15-2018 01:00:00","value":100},
{time:"01-15-2018 02:00:00","value":100},
{time:"01-15-2018 03:00:00","value":50},
{time:"01-15-2018 04:00:00","value":0}
]
},
{
"statusid": 1,
"status": “Processing”,
"requestcount":100,
"minvalue":0,
"maxvalue":75,
"items":[
{time:"01-15-2018 00:00:00","value":0},
{time:"01-15-2018 01:00:00","value":0},
{time:"01-15-2018 02:00:00","value":0},
{time:"01-15-2018 03:00:00","value":25},
{time:"01-15-2018 04:00:00","value":75}
]
},
{
"statusid": 7,
"Status": "Invalid",
"requestcount":50,
"minvalue":0,
"maxvalue":50,
"items":[
{time:"01-15-2018 00:00:00","value":0},
{time:"01-15-2018 01:00:00","value":0},
{time:"01-15-2018 02:00:00","value":0},
{time:"01-15-2018 03:00:00","value":25},
{time:"01-15-2018 04:00:00","value":25}
]
}]
}
OperationID 値を使用して、無効または処理中要求をフォローアップできます。
コードが沢山見ましたね。コードについてはひと休みして、最後の単元では連絡先の削除時の間違いを避ける最適な方法を学習します。
リソース
- Salesforce Developers: Contact Delete Configuration (連絡先の削除の構成)
- Salesforce Developers: Delete by Contact ID (連絡先 ID による削除)
- Salesforce Developers: Delete by Contact Key (連絡先キーによる削除)
- Salesforce Developers: Delete by List Reference (リスト参照による削除)
- Salesforce Developers: Contact Delete Status (連絡先の削除のステータス)
- Salesforce Developers: Contact Delete Requests Details (連絡先の削除要求の詳細)
- Salesforce Developers: Contact Delete Requests Summary (連絡先の削除要求のサマリー)