本記事では、「セグメント条件更新API」の概要・利用前提・仕様(リクエスト/レスポンス/エラーメッセージ)について紹介しています。
貴社の基幹システム/アプリケーションに連携したセグメント更新を行いたい場合は、本記事をご参照のもと、貴社開発環境に実装してください。

本記事の構成は下記の通りです。

　1. セグメント条件更新APIとは(概要 / b→dash管理画面上のデータ)
　2. 本API利用にあたっての前提事項(事前準備 / 共通仕様)
　3. セグメント条件更新APIの仕様(処理フロー / リクエスト / レスポンス)

各セクションの詳細は、以下をご参照ください。

1. セグメント条件更新APIとは

本APIの概要

セグメント条件更新APIとは、貴社の基幹システム/アプリケーションとb→dashを繋ぐことで、b→dash管理画面を介さずに、「セグメント」アプリ上のセグメント用データに対して、「絞り込み条件」や「更新条件」を変更/更新することができるAPIです。

※ 本APIはセグメントの条件更新のリクエストのみ行うAPIのため、条件更新の結果を確認することはできません。セグメント条件更新結果を確認したい場合は、『セグメント一覧取得APIを開発したい』も併せてご活用ください

本APIで更新できるb→dash管理画面上のデータ

セグメント条件更新APIでは、b→dash管理画面にある「セグメント編集画面」における操作と同様に、カラムに対して条件指定を行うことでレコードを絞り込むことができます。

※ 複合セグメントの場合は、「編集」をクリックしても上記の編集画面に遷移しません。複合セグメント作成時に「ベースセグメント」「追加セグメント」として選択した単一セグメントの編集画面をご参照ください
※ 本APIでは、セグメントの抽出条件の設定方法である「特定のデータファイルの値を抽出条件に用いる」機能を利用することはできません

本APIを利用した結果は、下記のb→dash管理画面で確認できます。

　・「セグメント一覧画面」
　・「セグメント詳細画面」(データファイル利用状況モーダル)

2. 本API利用にあたっての前提事項

事前準備

本APIを利用する事前準備として、下記の3つの手順を踏む必要があります。

　1. セグメント用データの作成
　2. 参照データファイルの取込設定
　3. セグメント利用施策の運用停止

1. セグメント用データの作成

b→dash管理画面上で更新対象となるセグメント用データを作成する必要があります。

※ セグメント用データの作成がまだ完了していない場合は『セグメントを作成したい』をご参照の上、設定を完了させてください

2. 参照データファイルの取込設定

本APIの利用でセグメントの「更新条件」を変更する場合、セグメント用データを作成する際に参照したデータファイルのデータファイル取込設定が「定期更新設定する」を選択している必要があります。

※ データファイル取込設定をもう一度見直したい場合は『データを取り込みたい』をご参照の上、設定を完了させてください

3. セグメント利用施策の運用停止

本APIの利用でセグメントの「絞り込み条件」を変更する場合、更新するセグメントを利用している施策(メールアプリ、データ分析など)の運用を停止する必要があります。
更新したいセグメントがどの施策で利用されているか、利用している施策が「運用中」であるかは、「利用状況モーダル」で確認できます。必要に応じて施策を運用停止し、利用状況モーダルのステータスを「運用停止」または「運用終了」にしてください。

共通仕様

本APIでは、b→dash APIの共通仕様も参照する必要があります。

※ 共通仕様の詳細については『b→dash APIの共通仕様を知りたい』をご参照ください

3. セグメント条件更新APIの仕様

処理フロー図

セグメント条件更新APIの処理フロー図は下記の通りです。

セグメント条件更新リクエスト

リクエストURIとURIパラメータ

本APIのURIにURIパラメータを指定して、データ連携をリクエストするリクエストURIを準備します。

URIパラメータは下記の通りです。

リクエストURIサンプル

https://api.smart-bdash.com/api/v1/segments/10

※ URIパラメータは、URIの「{xxx_xx}」に該当する値を代入することで指定できます

リクエストボディパラメータ

json形式のファイル(拡張子: .json)に、下記のリクエストボディパラメータを指定して、セグメントの更新内容を送信するためのリクエストボディを準備します。

レコード絞り込み条件と指定方法の一覧

本APIはカラムに対して条件指定を行うことで取得するレコードの絞り込みができます。下記に「絞り込み条件」と「コードの指定方法」をまとめておりますので、レコードの絞り込みを行う場合はご参照ください。

リクエストボディサンプル

{
  "segment_conditions": {
    "condition_or": [ 
      {
        "condition": [
          {
            "column_id": "COLUMN_1",
            "condition_name": "EQ",
            "condition_value": {
              "value": "vwxyz"
            }
          },
          {
            "column_id": "COLUMN_2",
            "condition_name": "BW",
            "condition_value": {
              "from": "20220101",
              "to": "20221231235959"
            }
          },
          {
            "column_id": "COLUMN_3",
            "condition_name": "NW",
            "condition_value": {
              "from": "20220101000000",
              "to": "20221231235959"
            }
          },
          {
            "column_id": "COLUMN_4",
            "condition_name": "T"
            }
          ]
        }
      ]
    },
  "aggregation_timing_settings": {
    "regular_update_settings": [
      {
        "interval": "MONTHLY",
        "day": 31,
        "hour": 23,
        "minute": 0
      },
      {
        "interval": "WEEKLY",
        "day_of_the_week": "FRI",
        "hour": 23,
        "minute": 0
      }
    ],
    "is_linked_to_datafile_update": true,
    "name": "更新後セグメント名称"
  }
}

リクエストヘッダパラメータ

準備したリクエストURI/リクエストボディと、下記のリクエストヘッダパラメータを用いて、貴社Webアプリから「PUT」リクエスト形式でセグメント条件更新のリクエストをします。

リクエストコードサンプル

PUT https://api.smart-bdash.com/api/v1/segments/10

セグメント条件更新レスポンス

レスポンスボディパラメータ

リクエストの送信に成功すると、下記のレスポンス形式で本APIからレスポンスが返されます。

成功レスポンスサンプル (202)

{
  "result": {
    "code": 202,
  }
}

※ セグメント条件更新APIで受け取るレスポンスは、セグメント更新処理が正常に開始されたかどうかのレスポンスであり、セグメント更新処理の結果ではありません

リクエストエラー発生時のエラーメッセージ詳細