シェア:
){kind=small}
スタンダップ・コメディーの学位論文を持つ俳優の訓練を受け、ミートアップ・シーンを経てPHP開発に携わるようになった。技術について話したり書いたり、レコード・コレクションから変わったレコードを再生したり買ったりしています。
Verify用テンプレート管理のご紹介
所要時間：1 分
開発者は、OTP（ワンタイムパスワード）で送信されるメッセージをカスタマイズできるようになりました。ワンタイムパスワード (OTP)で送信されるメッセージをカスタマイズできるようになりました。この機能は広範囲に及ぶので、この記事ではその実装方法と動作について説明する。
テンプレート管理により、開発者は、サポートされているロケール全体で SMS または Voice の OTP 配信メッセージを変更できます。これらは カスタムテンプレート.新しいVerifyリクエストは、リクエストが送信されるロケールを検出するか、リクエストで指定されたロケールを使用することができます。Verifyは次に、そのロケールとチャネルのカスタムテンプレートを作成したかどうかを確認し、存在すればそれを使用する。もし存在しなければ、Vonageの定型テンプレートを使おうとします。また、そのチャネル内でサポートされていないロケールを使っている場合は、最終的にen_USをデフォルトにします。
テンプレート管理機能は、Verifyするための10個の新しいAPIエンドポイントのセットで、当社のHAL標準に従ってコード化されています。 VonageのHAL標準.
カスタムテンプレートには2つの重要なエンティティがあります。テンプレートは非常に大きくなる可能性があるため（考えてみてください：1つのテンプレートが3つのチャネルすべてにわたって15のロケールに使用されるということは、45の別々の組み合わせを意味します）、カスタムテンプレートは2つの論理的な部分に分割されます：
* テンプレート template一意な名前を持ち、GUIDとそのチャンネルとロケールのデフォルトテンプレートかどうかが含まれます (作成時には常にデフォルトに設定され、後で変更することができます)。
* template_fragmentsと一対一の関係を持つエンティティである。 template.テンプレートに添付されるフラグメントは localeと channelの一意の組み合わせである。 textテンプレートの内容、およびタイムスタンプを持つ。
フラグメントを作成する際、メッセージテキスト内で使用できる静的変数がいくつかあります。ここで注意しなければならないのは メッセージにはコードを含んでいなければならないということです。 ${code}.他にも予約済みの静的変数がありますが、ここではそのすべてを紹介します：
${code}- エンドユーザーが入力するコード${brand}- リクエストで使用されるブランドパラメータ${time-limit}- 有効期限を表す整数${time-limit-unit}- 時間の単位を表す文字列
カスタムテンプレートが2つのロケールで使用されていることを示すハッピーパスを見てみよう。 en-gbそして fr_frSMS 配信のために使用されているカスタム・テンプレートを紹介する。現在、VonageのAPI Platformにサインアップし、テストリクエストを送信する。SMSは次のようなメッセージを表示する。 brandを "ACME "として送信したと仮定すると、以下のメッセージが表示されます：
ACME code: 5244. Valid for 3 minutes
よし、変えてみよう。まず、以下のリクエストを使ってテンプレートを作成する必要がある：
POST https://api.nexmo.com/v2/verify/templates
{
"name": "acme-template"
}作成されたことを知らせるHTTP 201が返ってくる：
HTTP 201
{
"template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
"name": "acme-template",
"is_default": true,
"_links": {
"self": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
},
"fragments": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
}
}
}ここで、2つのロケール用に2つのフラグメントを作成する必要がある。これは次の2つのリクエストで行います：
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "en-gb",
"text": "Thank you for continuing to use ${brand}! Your OTP is: ${code}"
}
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "fr-fr",
"text": "Merci de continuer à utiliser ${brand}! Votre OTP est: ${code}"
}どちらも201の返事が返ってくるはずだ。カスタマイズは完了したので、これら2つのメッセージをトリガーするメソッドは全部で4つある：
この例の新規Verifyリクエストでは、カスタム en_GBメッセージになります：
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "447700900000"
}
]
}
ここで en-gbここでテンプレートが自動的にピックアップされるのは、Verifyがこの番号にUK番号が含まれていることを検出したからです。 to番号にUK番号が含まれていることをVerifyが検出したためで、テンプレートにマッピングされます。しかし、代わりに localeを指定することができるので、カナダの番号（公用語は英語とフランス語の両方）に送信するが、英語が使われるようにしたいというような使用例が考えられます：
POST
https://api.nexmo.com/v2/verify
{
"locale": "en-gb"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "17700900000"
}
]
}この2つのシチュエーションは、フランス語翻訳でも使用できます。
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}ありがとう！最後に、ベトナムの電話番号に送ることができますが、フランス語のテンプレートが必要です：
POST
https://api.nexmo.com/v2/verify
{
"locale": "fr-fr"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}
どのロケールを送信するかを決めるのは、基本的に「ネット」である。かなりの数の選択肢があるので、この決定木は次のようになる：
Verify locale logic
非常に複雑に見えるかもしれないが、プロセスの最後に「エラー」がないことに注意することが重要である。もし他のすべてが失敗した場合、英語によるデフォルトのVonageテンプレートがコード付きで提供される。エンドユーザーは全文を理解することはできないかもしれないが、コロンの後のコードを認識する可能性は非常に高い。
カスタムテンプレートを使用しようとしたときに遭遇する可能性のある一般的なエラーをいくつか紹介します：
アカウントが有効になっていない
テンプレートを読むことはすべてのユーザーが可能ですが、カスタムテンプレートの作成はアカウントで有効にする必要があります。この機能を有効にするには、アカウントマネージャーに連絡するか、サポートにご相談ください。
テンプレートまたはフラグメントが存在する
各テンプレートは一意な名前を持たなければならず、そのテンプレート上の各フラグメントは、ロケールとチャンネルを組み合わせた一意なエントリでなければならない。
フラグメントを含むテンプレートを削除しようとしている
既存のフラグメントがある場合は、テンプレートを削除することはできません。テンプレート自身を削除する前に、テンプレート取得レスポンスのディスカバリー用HALフィールドを使って、削除する既存のフラグメントのIDをたどることができます。
使用しない
${code}本文中で
フラグメントを作成する際には、テキスト内にコードを含める必要があります。エンドユーザーにコードを提供しない場合、二要素認証システムがないことになり、APIはこれを許可しません。
テンプレートの最大数
テンプレートは1ユーザーにつき10個までで、それ以上生成しようとするとエラーになります。
カスタム・テンプレートはVerifyの比較的大きな追加機能ですが、まだ終わりではありません！それまでは、私たちの コミュニティSlackにご連絡ください。