twilio aspnet
8.1.1
ASP.NET（Twilio.aspNet）のTwilioヘルパーライブラリは、C＃および.NET用の公式Twilio SDKをASP.NETアプリケーションに統合するのに役立ちます。ライブラリは、.NETフレームワークとASP.NETコアでASP.NET MVCをサポートしています。
このライブラリは、Webhooksに応答し、Twilioクライアントを依存噴射コンテナに追加し、TwilioからのHTTP要求を検証するのに役立ちます。
.NET 6.0以降が必要です。
次のコマンドを実行して、.NET CLIを使用してパッケージをインストールします。
dotnet add package Twilio.AspNet.Coreまたは、パッケージマネージャーコンソールまたは開発者PowerShellから、次のコマンドを実行して最新バージョンをインストールします。
Install-Package Twilio.AspNet.Coreまたは、Visual StudioにNuget Package ManagerまたはJetBrains RiderにNugetウィンドウを使用してから、 twilio.aspnet.coreを検索してパッケージをインストールします。
.NET 4.6.2以降が必要です。
パッケージマネージャーのコンソールまたは開発者PowerShellから、次のコマンドを実行して最新バージョンをインストールします。
Install-Package Twilio.AspNet.Mvcまたは、Visual StudioにNuget Package ManagerまたはJetBrains RiderのNugetウィンドウを使用してから、 twilio.aspnet.mvcを検索してパッケージをインストールします。
using Twilio . AspNet . Common ;
using Twilio . AspNet . Core ; // or .Mvc for .NET Framework
using Twilio . TwiML ;
public class SmsController : TwilioController
{
// GET: Sms
public TwiMLResult Index ( SmsRequest request )
{
var response = new MessagingResponse ( ) ;
response . Message ( $ "Ahoy { request . From } !" ) ;
return TwiML ( response ) ;
}
}このコントローラーは、SMS Webhookを処理します。着信SMSの詳細は、 SmsRequest requestパラメーターにバインドされます。 TwilioControllerから継承することにより、 TwiMLメソッドにアクセスできるようになり、TWIMLで使用できます。
using Twilio . AspNet . Common ;
using Twilio . AspNet . Core ; // or .Mvc for .NET Framework
using Twilio . TwiML ;
public class VoiceController : TwilioController
{
// GET: Voice
public TwiMLResult Index ( VoiceRequest request )
{
var response = new VoiceResponse ( ) ;
response . Say ( $ "Ahoy! Are you from { request . FromCity } ?" ) ;
return TwiML ( response ) ;
}
}このコントローラーは、音声Webhookを処理します。着信音声呼び出しの詳細は、 VoiceRequest requestパラメーターにバインドされます。 TwilioControllerから継承することにより、 TwiMLメソッドにアクセスできるようになり、TWIMLで使用できます。
TwilioControllerから継承する代わりに、 TwiML拡張メソッドを使用しますTwilioControllerクラスから継承できない場合は、 TwiML拡張法を使用できます。
using Microsoft . AspNetCore . Mvc ; // or System.Web.Mvc for .NET Framework
using Twilio . AspNet . Common ;
using Twilio . AspNet . Core ; // or .Mvc for .NET Framework
using Twilio . TwiML ;
public class SmsController : Controller
{
// GET: Sms
public TwiMLResult Index ( SmsRequest request )
{
var response = new MessagingResponse ( ) ;
response . Message ( $ "Ahoy { request . From } !" ) ;
return this . TwiML ( response ) ;
}
}このサンプルは、以前のSMS Webhookサンプルと同じですが、 TwilioControllerから継承する代わりに、 SmsControllerはASP.NET MVC提供Controllerから継承し、 TwiML拡張法を使用するためにthis.TwiML使用します。
Twilio.aspnet.coreには、最小限のAPIのサポートもあります。
このサンプルは、HTTP Getと投稿を使用してSMS Webhookを担当する方法を示しています。
using Microsoft . AspNetCore . Mvc ;
using Twilio . AspNet . Core . MinimalApi ;
using Twilio . TwiML ;
var builder = WebApplication . CreateBuilder ( args ) ;
var app = builder . Build ( ) ;
app . MapGet ( "/sms" , ( [ FromQuery ] string from ) =>
{
var response = new MessagingResponse ( ) ;
response . Message ( $ "Ahoy { from } !" ) ;
return Results . Extensions . TwiML ( response ) ;
} ) ;
app . MapPost ( "/sms" , async ( HttpRequest request ) =>
{
var form = await request . ReadFormAsync ( ) ;
var from = form [ "from" ] ;
response . Message ( $ "Ahoy { from } !" ) ;
return Results . Extensions . TwiML ( response ) ;
} ) ;
app . Run ( ) ;従来のMVCコントローラーでは、 SmsRequest 、 VoiceRequest 、およびその他の入力リクエストオブジェクトがバインドされますが、最小限のAPIは同じモデルバインディングをサポートしません。
代わりに、 FromQuery属性を使用してHTTP GETリクエストの個々のパラメーターをバインドできます。 FromQuery属性を指定しない場合、クエリ文字列パラメーターに加えて、複数のソースがバインドすると見なされます。 HTTPの投稿リクエストの場合、フォームをつかみ、文字列インデックスで個々のパラメーターを取得できます。
twimlで応答するには、 Results.Extensions.TwiMLメソッドを使用します。
Twilio.aspnetには、Webhooksのデータを強く入力された.NETオブジェクトにバインドするのに役立つ複数のクラスが付属しています。クラスのリストは次のとおりです。
SmsRequest ：SMS Webhookリクエストのデータを保持しますSmsStatusCallbackRequest ：アウトバウンドTwilio SMSまたはMMSの配信ステータスを追跡するためのデータを保持しますStatusCallbackRequest ：アウトバウンドTwilio音声コールのステータスを追跡するためのデータを保持しますVoiceRequest ：着信音声通話のデータを保持しますメモMVCコントローラーとカミソリページのみが、型付けされた.NETオブジェクトへのモデルバインディングをサポートしています。最小限のAPIやその他のシナリオでは、パラメーターを自分で抽出するためにコードを記述する必要があります。
次のサンプルは、インバウンドSMSを受け入れ、応答し、SMS応答のステータスを追跡する方法を示しています。
using Twilio . AspNet . Common ;
using Twilio . AspNet . Core ; // or .Mvc for .NET Framework
using Twilio . TwiML ;
public class SmsController : TwilioController
{
private readonly ILogger < SmsController > logger ;
public SmsController ( ILogger < SmsController > logger )
{
this . logger = logger ;
}
public TwiMLResult Index ( SmsRequest request )
{
var messagingResponse = new MessagingResponse ( ) ;
messagingResponse . Message (
body : $ "Ahoy { request . From } !" ,
action : new Uri ( "/Sms/StatusCallback" ) ,
method : Twilio . Http . HttpMethod . Post
) ;
return TwiML ( messagingResponse ) ;
}
public void StatusCallback ( SmsStatusCallbackRequest request )
{
logger . LogInformation ( "SMS Status: {Status}" , request . MessageStatus ) ;
}
}上記のサンプルに示すように、 SmsRequestパラメーターとして追加でき、MVCはオブジェクトをバインドします。次に、コードは、 statusとmethodパラメーターを使用してSMSで応答します。 SMSのステータスが変更されると、TwilioはStatusCallbackアクションにHTTP POSTリクエストを送信します。 SmsStatusCallbackRequestをパラメーターとして追加でき、MVCはオブジェクトをバインドします。
ASP.NET Coreでは、TwilioRestAPIクライアント.AddTwilioClient ASP.NET Coreのサービスに追加できます。
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services . AddTwilioClient ( )これで、依存関係注入を介してITwilioRestClientとTwilioRestClient要求できます。
次の構成を使用して、Twilioクライアントを構成できます。
{
"Twilio" : {
"AuthToken" : " [YOUR_AUTH_TOKEN] " ,
"Client" : {
"AccountSid" : " [YOUR_ACCOUNT_SID] " ,
"AuthToken" : " [YOUR_AUTH_TOKEN] " ,
"ApiKeySid" : " [YOUR_API_KEY_SID] " ,
"ApiKeySecret" : " [YOUR_API_KEY_SECRET] " ,
"CredentialType" : " [Unspecified|AuthToken|ApiKey] " ,
"Region" : null ,
"Edge" : null ,
"LogLevel" : null
}
}
}いくつかのメモ：
Twilio:Client:AuthToken Twilio:AuthToken 。それらのいずれかを構成するだけです。Twilio:Client:CredentialTypeには、 Unspecified 、 AuthToken 、またはApiKey有効な値があります。Twilio:Client:CredentialTypeはオプションであり、デフォルトはUnspecifiedです。 Unspecified場合、APIキーまたはAUTHトークンを構成したかどうかが検出されます。.NET構成を使用してTwilioクライアントを構成したくない場合は、手動で行うことができます。
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services
. AddTwilioClient ( ( serviceProvider , options ) =>
{
options . AccountSid = "[YOUR_ACCOUNT_SID]" ;
options . AuthToken = "[YOUR_AUTH_TOKEN]" ;
options . ApiKeySid = "[YOUR_API_KEY_SID]" ;
options . ApiKeySecret = "[YOUR_API_KEY_SECRET]" ;
options . Edge = null ;
options . Region = null ;
options . LogLevel = null ;
options . CredentialType = CredentialType . Unspecified ;
} ) ;警告認証トークンまたはAPIキーシークレットをコードにハードコードせず、ソースコントロールにそれらをチェックしないでください。 Secrets Managerをローカル開発に使用することをお勧めします。または、環境変数、ボールトサービス、またはその他のより安全なテクニックを使用できます。
デフォルトでは、 .AddTwilioClientを呼び出すと、Twilio RESTクライアントにHttpClientを提供するために使用されるHTTPクライアントファクトリが構成されています。このHTTPクライアントをカスタマイズしたい場合は、 .AddTwilioClientを呼び出した後、「twilio」HTTPクライアントファクトリをオーバーライドすることでそうすることができます。
builder . Services . AddTwilioClient ( ) ;
builder . Services . AddHttpClient ( "Twilio" )
. ConfigureHttpClient ( client =>
{
client . BaseAddress = new Uri ( "YOUR_PROXY_ADDRESS" ) ;
} )
. ConfigurePrimaryHttpMessageHandler ( ( ) => new HttpClientHandler
{
// same options as the Twilio C# SDK
AllowAutoRedirect = false
} ) ;WebHooksはエンドポイントを公開する必要がありますが、これにより、悪い俳優がWebHook URLを見つけて悪用しようとするリスクも導入されます。
幸いなことに、HTTPリクエストがTwilioから発生したことを確認できます。 Twilio.AspNetライブラリは、MVCでお客様のリクエストを検証する属性を提供します。実装はTwilio.AspNet.Mvc Twilio.AspNet.Coreライブラリの間で異なります。
起動時に.AddTwilioRequestValidationメソッドを追加します。
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services . AddTwilioRequestValidation ( ) ;次に、リクエストの検証を構成します。
{
"Twilio" : {
"AuthToken" : " [YOUR_AUTH_TOKEN] " ,
"RequestValidation" : {
"AuthToken" : " [YOUR_AUTH_TOKEN] " ,
"AllowLocal" : false ,
"BaseUrlOverride" : " https://??????.ngrok.io "
}
}
}構成に関するいくつかのメモ：
Twilio:RequestValidation:AuthToken Twilio:AuthToken 。それらのいずれかを構成するだけです。AllowLocal 、HTTP要求がLocalHostから発信されたときに検証をスキップします。BaseUrlOverrideを使用してください。現在のリクエストのパスは、リクエスト検証のためにBaseUrlOverrideに追加されます。情報
BaseUrlOverrideを構成する代わりに、転送されたヘッダーミドルウェアを使用して、現在のHTTPリクエストで正しいスキーム、ポート、ホストなどを設定できます。
using Microsoft . AspNetCore . HttpOverrides ;
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services . AddTwilioRequestValidation ( ) ;
builder . Services . Configure < ForwardedHeadersOptions > ( options => options . ForwardedHeaders = ForwardedHeaders . All ) ;
// more service configuration
var app = builder . Build ( ) ;
app . UseForwardedHeaders ( ) ;
// more request pipeline configuration
app . Run ( ) ;その結果、ngrokを再起動するたびにBaseUrlOverrideを構成したり、逆プロキシURLを変更する必要はありません。 Microsoftのガイダンスに従って、転送されたヘッダーミドルウェアを安全に構成します。
リクエストの検証を手動で構成することもできます。
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services
. AddTwilioRequestValidation ( ( serviceProvider , options ) =>
{
options . AuthToken = "[YOUR_AUTH_TOKEN]" ;
options . AllowLocal = false ;
options . BaseUrlOverride = "https://??????.ngrok.io" ;
} ) ;警告認証トークンをコードにハードコードせず、ソースコントロールにそれらをチェックしないでください。 Secrets Managerをローカル開発に使用することをお勧めします。または、環境変数、ボールトサービス、またはその他のより安全なテクニックを使用できます。
リクエスト検証が構成されたら、MVCで[ValidateRequest]属性を使用できます。属性をグローバルに、MVCエリア、コントローラー、およびアクションに適用できます。属性がIndexアクションに適用される例は次のとおりです。
using Twilio . AspNet . Common ;
using Twilio . AspNet . Core ;
using Twilio . TwiML ;
public class SmsController : TwilioController
{
[ ValidateRequest ]
public TwiMLResult Index ( SmsRequest request )
{
var response = new MessagingResponse ( ) ;
response . Message ( "Ahoy!" ) ;
return TwiML ( response ) ;
}
} .NET 7は、ASP.NETコアエンドポイントに適用できるエンドポイントフィルターの概念を紹介します。 ASP.NET Coreのヘルパーライブラリは、 ValidateTwilioRequestFilterと呼ばれるtwilio要求を検証するエンドポイントフィルターを追加しました。
このフィルターは、 ValidateTwilioRequestメソッドを使用して、任意のエンドポイントまたはエンドポイントグループに追加できます。
// add filter to endpoint
app . MapPost ( "/sms" , ( ) => .. . )
. ValidateTwilioRequest ( ) ;
// add filter to endpoint group
var twilioGroup = app . MapGroup ( "/twilio" ) ;
twilioGroup . ValidateTwilioRequest ( ) ;
twilioGroup . MapPost ( "/sms" , ( ) => .. . ) ;
twilioGroup . MapPost ( "/voice" , ( ) => .. . ) ;または、エンドポイントフィルターを自分で追加することもできます。
app . MapPost ( "/sms" , ( ) => .. . )
. AddEndpointFilter < ValidateTwilioRequestFilter > ( ) ; [ValidateRequest]フィルターまたはValidateTwilioRequestFilterを使用できない場合は、代わりにValidateTwilioRequestMiddlewareを使用できます。このようにValidateTwilioRequestFilterを追加できます。
app . UseTwilioRequestValidation ( ) ;
// or the equivalent: app.UseMiddleware<ValidateTwilioRequestMiddleware>();このミドルウェアは、すべてのリクエストの検証を実行します。すべてのリクエストに検証を適用したくない場合は、 app.UseWhen()を使用してミドルウェアを条件付きで実行できます。
Twilioプロキシのみがアクセスできるはずのメディアファイルを保護するために、Path /Twilio-Mediaから始まるリクエストを検証する方法の例を次に示します。
using System . Net ;
using Microsoft . Extensions . FileProviders ;
using Microsoft . Extensions . Options ;
using Twilio . AspNet . Core ;
var builder = WebApplication . CreateBuilder ( args ) ;
builder . Services . AddTwilioRequestValidation ( ) ;
var app = builder . Build ( ) ;
app . UseWhen (
context => context . Request . Path . StartsWithSegments ( "/twilio-media" , StringComparison . OrdinalIgnoreCase ) ,
app => app . UseTwilioRequestValidation ( )
) ;
app . UseStaticFiles ( new StaticFileOptions
{
FileProvider = new PhysicalFileProvider ( Path . Combine ( builder . Environment . ContentRootPath , "TwilioMedia" ) ) ,
RequestPath = "/twilio-media"
} ) ;
app . Run ( ) ; web.configでは、以下に示すようにリクエストの検証を構成できます。
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< configuration >
< configSections >
< sectionGroup name = " twilio " type = " Twilio.AspNet.Mvc.TwilioSectionGroup,Twilio.AspNet.Mvc " >
< section name = " requestValidation " type = " Twilio.AspNet.Mvc.RequestValidationConfigurationSection,Twilio.AspNet.Mvc " />
</ sectionGroup >
</ configSections >
< twilio >
< requestValidation
authToken = " [YOUR_AUTH_TOKEN] "
baseUrlOverride = " https://??????.ngrok.io "
allowLocal = " false "
/>
</ twilio >
</ configuration >アプリ設定を使用して、リクエスト検証を構成することもできます。
<? xml version = " 1.0 " encoding = " utf-8 " ?>
< configuration >
< appSettings >
< add key = " twilio:requestValidation:authToken " value = " [YOUR_AUTH_TOKEN] " />
< add key = " twilio:requestValidation:baseUrlOverride " value = " https://??????.ngrok.io " />
< add key = " twilio:requestValidation:allowLocal " value = " false " />
</ appSettings >
</ configuration >両方の方法を使用してリクエスト検証を構成すると、アプリ設定はtwilio/requestValidation構成要素を上書きします。
構成に関するいくつかのメモ：
allowLocal 、HTTP要求がLocalHostから発信されたときに検証をスキップします。baseUrlOverride使用してください。現在のリクエストのパスは、リクエスト検証のためにbaseUrlOverrideに追加されます。警告認証トークンをコードにハードコードせず、ソースコントロールにそれらをチェックしないでください。ローカル開発または他の構成ビルダーのいずれかには、
UserSecretsConfigBuilderを使用します。または、Auth Tokenなどの秘密を含む構成セクションを暗号化する必要があります。
要求の検証が構成された今、 [ValidateRequest]属性を使用します。属性をグローバルに、MVCエリア、コントローラー、およびアクションに適用できます。属性がIndexアクションに適用される例は次のとおりです。
using Twilio . AspNet . Common ;
using Twilio . AspNet . Mvc ;
using Twilio . TwiML ;
public class SmsController : TwilioController
{
[ ValidateRequest ]
public TwiMLResult Index ( SmsRequest request )
{
var response = new MessagingResponse ( ) ;
response . Message ( "Ahoy!" ) ;
return TwiML ( response ) ;
}
} [ValidateRequest]属性は、MVCでのみ機能します。 MVC以外のリクエストを検証する必要がある場合は、 Twilio.AspNetが提供するRequestValidationHelperクラスを使用できます。または、Twilio SDKのRequestValidatorクラスもこれを支援できます。
これは、Twilioに由来する着信要求を検証する最小限のAPI例です。
using System . Net ;
using Microsoft . Extensions . Options ;
using Twilio . AspNet . Core ;
using Twilio . AspNet . Core . MinimalApi ;
using Twilio . TwiML ;
var builder = WebApplication . CreateBuilder ( args ) ;
// adds TwilioRequestValidationOptions
builder . Services . AddTwilioRequestValidation ( ) ;
var app = builder . Build ( ) ;
app . MapPost ( "/sms" , ( HttpContext httpContext ) =>
{
if ( IsValidTwilioRequest ( httpContext ) == false )
return Results . StatusCode ( ( int ) HttpStatusCode . Forbidden ) ;
var messagingResponse = new MessagingResponse ( ) ;
messagingResponse . Message ( "Ahoy!" ) ;
return Results . Extensions . TwiML ( messagingResponse ) ;
} ) ;
app . Run ( ) ;
bool IsValidTwilioRequest ( HttpContext httpContext )
{
var options = httpContext . RequestServices
. GetService < IOptions < TwilioRequestValidationOptions > > ( )
? . Value ?? throw new Exception ( "TwilioRequestValidationOptions missing." ) ;
string ? urlOverride = null ;
if ( options . BaseUrlOverride is not null )
{
var request = httpContext . Request ;
urlOverride = $ " { options . BaseUrlOverride . TrimEnd ( '/' ) } { request . Path } { request . QueryString } " ;
}
return RequestValidationHelper . IsValidRequest ( httpContext , options . AuthToken , urlOverride , options . AllowLocal ) ;
} AddTwilioRequestValidation 、通常[ValidateRequest]属性に使用されるTwilioRequestValidationOptionsを追加しますが、このサンプルでは、リクエスト検証構成を自分で取得するために使用されます。次に、 /smsエンドポイントの内部では、 IsValidTwilioRequestメソッドを使用してリクエストを検証します。 IsValidTwilioRequest 、DIからリクエスト検証オプションを取得し、MVCリクエストに対して[ValidateRequest]が行うのと同じロジックを実行します。リクエストが有効でない場合、HTTPステータスコード403が返されます。そうしないと、一部のTWIMLがTwilioに返されます。
