NTT CPaaS APIを使ってみましょう

このドキュメンテーションにはNTT CPaaSのAPIでできることがすべて記載されています。また、左側のナビゲーションメニューではNTT CPaaSの製品群が一目でわかるようになっています。それぞれの製品には利用可能なAPIエンドポイントおよびWebhookすべてに関するドキュメンテーションが含まれています。

トライアルアカウント

NTT CPaaSのAPIはどなたも無料でお使いいただけますが、ご利用にはNTT CPaaSアカウントが必要です。サインアップのプロセスは簡単です。APIの利用開始に必要なものはAPIキーとベースURLのみで、サインアップ完了後に取得できます。トライアル期間中、選択した製品によっては一定の制約が発生します。代表的なものとして、以下が挙げられます。

• チャネルごとに送信できる無料メッセージの数
• 受信者のタイプ - 通常、メッセージ送信が可能な宛先は、サインアップ時に登録したお客様の番号またはメールアカウントのみです。
• 送信者ID - 事前に定義されたNTT CPaaSのデモ送信者しか使用できません

トライアルはアカウント作成日から60日間有効です。有料アカウントと同様、APIのパフォーマンスはスロットリングやスループット、その他、通信会社関連の制限によって影響が生じます。トライアルについて詳しくはこちらから。

認証

NTT CPaaSはさまざまな認証方法をサポートしていますが、可能な限りAPIキーヘッダーを使用することを推奨します。

ログイン後、Webインターフェースホームページ内、またはAPIキー管理ページのこのページの上部にAPIキーが表示されます。

ベースURLおよびデータセンター

NTT CPaaSの各アカウントには一意のベースURLが与えられ、毎回のAPIリクエストで使用することになります。NTT CPaaSにログインすると、お客様のベースURLはこのページの上部に表示されます。また、ドキュメンテーションすべての全APIエンドポイントおよびコード例に対し、ベースURLが挿入されます。

NTT CPaaSではリクエストを正しい「規制地域」へルーティングし、当該地域内のデータセンター間のトラフィックを最適化する場合に、ベースURLを使用します。また、ベースURLは当社のサポートチームが実施するトラブルシューティングにも使用されます。

詳細についてはベースURLを参照してください。

OpenAPIの仕様

NTT CPaaS APIの業界基準への適合と、円滑なインテグレーションを実現するため、当社のAPIはすべてOpenAPIの仕様の枠組みに従って設計されています。

詳しくはNTT CPaaS OpenAPIの仕様をご覧ください。

SDK

NTT CPaaSでは、公式APIクライアントライブラリを始め、各種プログラミング言語によるSDKを提供しています。すべてのSDKを確認する場合は、当社の開発者ハブでSDKページをご覧ください。

新規リリースについては、いわゆるセマンティック バージョニング 2.0.0基準に従っています。つまり、当社が公開するパッチやマイナーアップデートは後方互換が確保されていることから、新しいバージョンへのアップデートを安全に実行できるということです。メジャーリリースには、前バージョンと互換性のない変更が必ず含まれています。

NTT CPaaSのAPI関連のSDKはすべて、オープンソースとしてGitHubで公開されています。当社のライブラリは OpenAPIの仕様 の上位に設置され、OpenAPIジェネレータ によって運営されています。このため、NTT CPaaSではこれらのGitHubレポジトリに関するプルリクエストを受け付けていません。ただし、コントリビューションガイドラインにも記載があるように、新しい問題としてNTT CPaaSのレポジトリで提起することを強くお勧めします。

コード例

各APIエンドポイントには、必ずユースケースが記載されています。各ユースケースにはタスクの遂行方法に関して含むべき/除外すべきパラメータがあります（例．基本的なテキストSMS送信、SMSのスケジュール送信、特定言語によるSMS送信など）。各コード例は、curlコマンドの他にも複数のプログラミング言語で利用できるほか、JSONやXMLのリクエストペイロードとしても利用可能です。コード例は Postmanコードジェネレータ を使用してOpenAPIの仕様 から自動生成されます。ご自由にコード例をコピーしてお客様のプロジェクトでお使いください。

Webhook

メッセージ配信ステータスや受信メッセージステータスといった一定のイベントについて通知を受け取りたい場合は、Webhookを使用します。Webhookとは標準HTTPエンドポイントのことで、NTT CPaaSが送信したHTTPリクエストについて、その受け入れや処理を行うお客様側のアプリケーションに実装するものです。基本的にWebhookとは、メッセージ配信ステータスの問い合わせリクエストをNTT CPaaSサーバーに送り続けなくても済むようにするものです。代わりに入手可能な配信ステ－タスが指定されたエンドポイントに転送されます。これらのリクエストは通常、POSTリクエストとしてJSON形式のペイロードを含んでいます。Webhookの管理や構成にはサブスクリプション管理APIを使用します。

スパムからエンドポイントを保護する場合は、NTT CPaaSのIPアドレスを使って、NTT CPaaSプラットフォームから送信されたトラフィックをホワイトリストに登録できます。IPアドレスのセーフリストを確認してください。スパムからエンドポイントを保護する場合は、NTT CPaaSのIPアドレスを使って、NTT CPaaSプラットフォームから送信されたトラフィックをホワイトリストに登録できます。 IPアドレスのセーフリストを確認してください。

ステータスおよびエラーコード

ステータスコードについては、APIステータスコードの他にも結果ステータスコード（すべてのHTTPトランザクションについてサーバーから返信されるコード）をご用意しています。APIステータスコードは送信メッセージや配信レポート、メッセージログのレスポンスで確認できます。ここに表示することで送信メッセージのステータスが追跡可能となるだけでなく、トラブルシューティングの際にも非常に役立ちます。エラーコードはステータスコードと同様、送信メッセージや配信レポートのレスポンスの構成要素として返すことができます。

通常、レスポンスの一部として受け取るステータスはPENDING_ACCEPTEDと呼ばれるID 26のステータスです。このステータスは送信しようとするメッセージの受付と処理が成功し、オペレータに送信する準備が整ったことを通知するものです。

レスポンスステータスで重要なことは、エラーのないステータスを受信することです。例えば、NO_ERRORの名前を持つID 0のステータスです。

詳しい説明は応答ステータスおよびエラーコードを参照してください。

バージョニングおよびAPIライフサイクル

文書化された各APIエンドポイントのURLには現在のAPIバージョン番号が含まれています。エンドポイントバージョンは破壊的変更が導入された場合にのみ変更されます。例えば、新規フィールドの追加は破壊的変更とは見なされません。しかしフィールドの削除やモデル構造の変更は破壊的変更にあたります。新しいバージョンを導入すると、ドキュメンテーションでは既存のバージョンに「廃止」のラベルがつけられます。

NTT CPaaSのAPIエンドポイントを完全に廃止する場合、必ず6か月以上前にその旨を通知します。

このルールには例外があり、「早期アクセス」の名称が付けられた製品やエンドポイントなどがその例に当たります。その場合は対象となる製品/サービスの最新情報を常に把握し、イテレーションのサイクルを早めて、テストを実施するよう心がけてください。エンドポイントに早期アクセスのマークがついている場合でも、当社のログでお客様による最近のAPIの利用を確認した場合は、変更についてお知らせをいたします。

他の場合と同じように、このフェーズでもフィードバックを寄せていただければありがたく存じます。お客様からの貴重なご意見をお待ちしております。

スループットおよびスロットリング

よくお問い合わせをいただくのが、NTT CPaaSのAPIが処理できるトラフィック量についての質問です。これは呼び出されるAPIエンドポイントによって異なります。

メッセージ送信APIに上限はありません。大手グローバル企業の多くがNTT CPaaSのAPIを使用してメッセージを送信しており、当社はこれらのトラフィックのピークでも処理できる十分な能力と、処理に必要なリソースを有しています。ただし、NTT CPaaSとメッセージ受信者の間に介在するチャネルプロバイダによってはボトルネックが発生する恐れがあるため、注意が必要です。詳しくは関連製品のチャネルドキュメンテーションをご覧ください。

メッセージ送信を実行していないAPIエンドポイントはそれぞれ、使用率が通常の使用事例を大きく超える場合にリクエストをスロットリングするよう設定されています。スロットリングが実行されると、HTTPステータスコード429（リクエストが多すぎます）がエラーメッセージとして届きます。通常、この現象は、お客様がAPIエンドポイントを当初予定されていた使用法とは異なる状態で使用していることを示します。このような場合にはお客様の事例により適合する他のエンドポイントを検索するか、サポートにご相談することをお勧めします。

NTT CPaaSのスロットリングメカニズムは単位時間内の最大リクエスト数に基づいて構成されています。このため、APIリクエストの送信を停止して短時間待機すると、APIを再度呼び出すことができるようになります。

ベストプラクティス

NTT CPaaSのAPIをご利用の開発者向けに円滑なエクスペリエンスをご提供できるよう、当社では日々努力を重ねています。その実現に向けたひとつの方法として、当社では一定のアプローチや基準、慣行に一貫して従うことに注力しています。

お気づきかもしれませんが、NTT CPaaSのドキュメンテーションにあるコード例はURLエンコードに変換されていません。お客様がリクエストクエリのパラメータに明示的なURLエンコーディングを必要とするシステムやプログラミング言語、またはライブラリに依存している場合は、お客様側でエンコードする必要があります。この方式を決定した最大の理由は、コード例の読みやすさ、わかりやすさを優先したためです。この点に加え、HTTPコールをトリガーするプログラミング言語やライブラリのほとんどで、エンコードは内部で実行されています。

潜在的な問題の発生を防ぐための方法や、サポートされる日付形式、リクエスト・レスポンスの本文タイプ、その他、NTT CPaaSのAPI利用時に遵守すべきコーディングルールに関する詳細はインテグレーションのベストプラクティスを参照してください。

より快適にお使いいただくためのベストプラクティスをこちらに集めました。詳細をご確認ください。

インテグレーションおよびパートナーシッププログラム

インテグレーションの自社ソリューションに着手する前に、既存のインテグレーションの中にお客様に合った、第三者も利用可能なものがないか確認することをお勧めします。

お客様の調達したソリューションが他社でも活用できるとお考えの場合は、ぜひパートナーシップチームにご連絡ください。NTT CPaaSとの接続オプションによって他のプラットフォームが活用できれば幸いです。

当社では、パートナーシッププログラムに参加したお客様に無料の専門サービスや、グローバルな専門家による研修コースや認定証発行などの特典を提供しています。また、オンサイト販売や先行販売のサポート、マーケティング開発ファンドもご利用いただけます。

ヘルプとサポート

お困りの際には

• 使用中の製品のアップタイムステータスを確認してください。
• ドキュメンテーションハブをご利用ください。お役に立てる情報を掲載しています。
• バグの報告やアカウント固有の質問をお持ちの場合はサポートチーム宛てにチケットを発行するしてください。