ディスパッチからメッセージ・フェイルオーバーへの移行

このガイドでは、Dispatch API の機能と、Failover 機能の機能を比較しています。 Messages APIまた、Dispatch APIからMessages APIのFailover機能へ移行する際に注意すべき点を概説している。

一般概念

一般的な概念レベルでは、Dispatch APIとMessages APIのFailover機能は大まかに似ている。どちらも、次のようなことができます：

初期メッセージを指定し、初期メッセージが届かなかった場合に送信されるフォールバックメッセージを指定する。
異なるメッセージタイプ間のフェイルオーバー。
異なるメッセージング・チャネル間のフェイルオーバー。

しかし、注意すべき重要な違いもいくつかある。以下の表は、これらの違いのいくつかを簡単にまとめたものである。

Dispatch API	Messages API フェイルオーバー
に基づくフェイルオーバー・ロジック `condition_status` そして `expiry_time` プロパティ	メッセージに基づくフェイルオーバーロジック `rejected`
メッセージステータスのウェブフックには、個別メッセージと最終レポートの2種類があります。	メッセージステータスのウェブフックを1種類提供する
-	RCSなどの追加チャンネルと追加メッセージタイプをサポート
使用メッセージ v0.1	メッセージv1で実装
サーバーSDKではサポートされていません。	サーバーSDKでサポート

主な違い

Dispatch APIとMessages APIのフェイルオーバーの主な違いは、フェイルオーバーがトリガーされるロジックである。

Dispatch API は、以下のように定義されています。 workflow 配列には、ワークフローの各メッセージのオブジェクトが含まれます。そのオブジェクトの中に condition_status プロパティは status 指定された expiry_time.もしステータスが expiry_timeワークフローは次のメッセージにフェイルオーバーする。
Messages APIのフェイルオーバー機能は、初期メッセージのプロパティを定義し、オプションとして failover ワークフロー内の残りのメッセージのメッセージオブジェクトを含む配列。ワークフロー内の各メッセージに対して個別の条件を定義するのではなく、現在のメッセージのステータスが rejected.

この2つのAPIには、他にもいくつか注意すべき違いがある。これらについてはその他の考慮事項セクションを参照されたい。

リクエスト

どちらのAPIも POST リクエストをそれぞれのURL (https://api.nexmo.com/v0.1/dispatch/ Dispatch API と https://api.nexmo.com/v1/messages Messages API用)。

Dispatch APIはバックグラウンドでMessages APIを使用する（Dispatch APIは本質的には オーケストレーション層 を参照)、そのため、メッセージ・オブジェクトは含まれるプロパティに関して類似している。ただし、DispatchはMessages v0.1を使用し、Messages Failover機能はMessages v1で実装されています( その他の考慮事項そのため、メッセージ・オブジェクトのJSON構造は異なっている（v1はより平坦な構造を使用している）。

以下は両方のAPIを使ったリクエストの例である。

Dispatch API

{
   "template":"failover",
   "workflow": [
		{
			"from": { "type": "mms", "number": "447900000000" },
			"to": { "type": "mms", "number": "447900000001" },
			"message": {
				"content": {
				"type": "img",
				"image": { "url": "https://example.com/image.jpg" }
				}
			},
			"failover":{
				"expiry_time": 600,
				"condition_status": "delivered"
			}
		},
		{
			"from": {"type": "sms", "number": "447900000000"},
			"to": { "type": "sms", "number": "447900000001"},
			"message": {
				"content": {
				"type": "text",
				"text": "This is an SMS sent via the Dispatch API"
				}
			}
		}
   ]
}

上の例は、MMS画像メッセージからSMSテキストメッセージにフェイルオーバーするDispatch APIワークフローを示しています。もし delivered のMMS画像メッセージのステータスを受信しない。 600 秒後にSMSテキストメッセージが送信される。

Messages API

{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "mms",
	"message_type": "image",
	"image": {
		"url": "https://example.com/image.jpg"
	},
	"failover": [
		{
	"to": "447700900000",
	"from": "447700900001",
	"channel": "sms",
	"message_type": "text",
	"text": "Hello from Vonage!"
		}
	]
}

上記の例は、MMS画像メッセージからSMSテキストメッセージにフェイルオーバーするMessages APIワークフローを示しています。もし rejected MMS画像メッセージのステータスを受信すると、SMSテキストメッセージが送信されます。

回答

どちらのAPIもリクエストに成功すると同様のレスポンスを返す。

Dispatch API

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

について dispatch_uuid は、Message Status Webhook のコンテキストで Dispatch ワークフローを識別するために使用されます。

Messages API

{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

について message_uuid はすべてのリクエストに存在し、メッセージステータス Webhook のコンテキストで最初のメッセージを識別するために使用されます。これは workflow_id を含むリクエストに対してのみ存在する。 failover 配列であり、ワークフロー全体を識別するために使用される。

メッセージステータスWebhook

メッセージステータスWebhookは、個々のメッセージのステータスの変更によってトリガーされ、Vonageアカウント設定またはVonageアプリケーション設定で定義されたWebhookエンドポイントに送信されます。

メッセージオブジェクトそのものと同様に、Webhook ペイロードの JSON 構造も API 間で異なります。さらに、Dispatch API は 2 種類の Status webhook を送信するが、Messages API は 1 種類しか送信しない。

Dispatch API

Dispatch APIが送信する：

ステータスウェブフックは、ワークフロー内の個々のメッセージに関連して送信される。
最終報告書ステータスウェブフックは、ワークフロー内のメッセージが指定された expiry_time 以内に指定された condition_status を満たした場合、またはワークフロー内の最終メッセージが配送できなかった場合に送信される。

個別メッセージ・ウェブフック

これには message_uuid これはMessages APIとの関連で個々のメッセージを識別する。また workflow オブジェクトに dispatch_uuid このプロパティの値は、最初のリクエストに対するレスポンスで受け取ったものと一致し、Dispatchワークフロー全体を識別します。

{
	"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"to": {
		"type": "sms",
		"number": "447700900001"
	},
	"from": {
		"type": "sms",
		"number": "447700900000"
	},
	"timestamp": "2020-01-01T14:00:00.000Z",
	"status": "rejected",
	"error": {
		"code": 1300,
		"reason": "Not part of the provider network"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"_links": {
		"workflow": {
				"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
		}
	}
}

最終報告メッセージWebhook

これには dispatch_uuid このプロパティの値は、最初のリクエストに対するレスポンスで受け取ったものと一致し、全体的なDispatchワークフローを識別します。また、このプロパティには status どちらかの completed 指定された condition_status ワークフロー内のあるメッセージについて、以下のセットで満たされる。 expiry_timeあるいは error ワークフローの最終メッセージが配信できない場合。

{
	"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
	"template": "failover",
	"status": "completed",
	"timestamp": "2020-01-01T14:00:00.000Z",
	"usage": {
		"price": "0.02",
		"currency": "EUR"
	},
	"_links": {
		"messages": [
			{
				"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
				"channel": "mms",
				"usage": {
						"currency": "EUR",
						"price": "0.0333"
				},
				"status": "submitted"
			}
		]
	}
}

Messages API

Messages API は、次のように送信します。ステータスウェブフックステータスに変更があった場合。メッセージが failover プロパティが含まれていた場合、JSONペイロードには workflow オブジェクトになります。このオブジェクトには3つのプロパティが含まれる：

workflow_id:フェイルオーバー・ワークフローのユニーク ID。最初の API リクエストのレスポンスで返された workflow_id の値と一致する。
items_number:ステータスが関連するワークフロー内の特定のメッセージを示す。 1 最初のメッセージのために、 2 の最初のメッセージに対して failover 配列などである。
items_total:ワークフローで定義されたメッセージの総数。

{
	"message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
	"to": "447700900000",
	"from": "447700900001",
	"timestamp": "2025-02-03T12:14:25Z",
	"status": "delivered",
	"workflow": {
		"workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
		"items_number": "1",
		"items_total": "2"
	},
	"usage": {
		"currency": "EUR",
		"price": "0.0333"
	},
	"channel": "sms",
	"destination": {
		"network_code": "12345"
	},
	"sms": {
		"count_total": "2"
	}
}

その他の考慮事項

Dispatch API から Message API の Failover 機能に移行する際には、すでに説明した違いのほかにもいくつか注意すべき点がある。

Messages API バージョン

このドキュメントの他の部分で述べたように、Dispatch APIは基本的にMessages APIの上にあるオーケストレーションレイヤーだ。しかし、Messages APIには現在2つのバージョンがあることに注意する必要がある： v0.1 そして v1.Dispatch APIはMessages v0.1を使用し、Messages Failover機能はv1で実装されている。JSONペイロードの構造の違いの他に、特筆すべきバージョン間の違いがいくつかある。

メッセージ v1は、v0.1と比較して、追加のチャネルとメッセージ・タイプをサポートしている。例えば、v1はRCSチャネルをサポートしている（フェイルオーバーの一般的なユースケースは、RCSからSMSへの移行である）。両者でサポートされているチャネルの中でも、v1はMMSテキスト、ファイル、コンテンツ・メッセージ・タイプなど、いくつかの追加メッセージ・タイプをサポートしている。
その他にも、いくつもある。追加機能 v0.1と比較してv1で提供されるもの

サーバーSDK

Messages API (v1)はVonageに実装されています。サーバーSDK一方、Dispatch APIはそうではない。Server SDKのMessages API実装には、Messages Failover機能が含まれている。Node JS、PHP、Python、Java、Kotlin、.NET、Ruby用のServer SDKがあります。このSDKを使えば、APIエンドポイントのラッパーを独自に実装することなく、Messages APIをアプリケーションに簡単に統合できます。

その他のリソース

フェイルオーバー機能を含むDispatch APIとMessages APIの詳細については、以下のリンク先のドキュメントページを参照されたい：