Azure Mobile Apps 用 .NET バックエンド サーバー SDK の操作Work with the .NET backend server SDK for Azure Mobile Apps

注意

Visual Studio App Center は、モバイル アプリ開発の中心となるエンドツーエンドの統合サービスをサポートしています。Visual Studio App Center supports end to end and integrated services central to mobile app development. 開発者は、ビルドテスト配布のサービスを使用して、継続的インテグレーションおよびデリバリー パイプラインを設定できます。Developers can use Build, Test and Distribute services to set up Continuous Integration and Delivery pipeline. アプリがデプロイされたら、開発者は分析および診断のサービスを利用してアプリの状態と使用状況を監視し、プッシュ サービスを利用してユーザーと関わることができます。Once the app is deployed, developers can monitor the status and usage of their app using the Analytics and Diagnostics services, and engage with users using the Push service. また、開発者は Auth を利用してユーザーを認証し、データ サービスを利用してクラウド内のアプリ データを保持および同期することもできます。Developers can also leverage Auth to authenticate their users and Data service to persist and sync app data in the cloud.

モバイル アプリケーションにクラウド サービスを統合することを検討している場合は、今すぐ App Center にサインアップしてください。If you are looking to integrate cloud services in your mobile application, sign up with App Center today.

このトピックでは、Azure App Service Mobile Apps の主要なシナリオで .NET バックエンド サーバー SDK を使用する方法について説明します。This topic shows you how to use the .NET backend server SDK in key Azure App Service Mobile Apps scenarios. Azure Mobile Apps SDK を使用すると、ASP.NET アプリケーションからモバイル クライアントを操作することができます。The Azure Mobile Apps SDK helps you work with mobile clients from your ASP.NET application.

ヒント

Azure Mobile Apps 向け .NET サーバー SDK は、オープン ソースとして GitHub で公開されています。The .NET server SDK for Azure Mobile Apps is open source on GitHub. リポジトリには、サーバー全体の SDK ユニット テスト スイートといくつかのサンプル プロジェクトを含むすべてのソース コードが含まれています。The repository contains all source code including the entire server SDK unit test suite and some sample projects.

リファレンス ドキュメントReference documentation

サーバー SDK のリファレンス ドキュメントについては、Azure Mobile Apps .NET のリファレンスを参照してください。The reference documentation for the server SDK is located here: Azure Mobile Apps .NET Reference.

方法:.NET モバイル アプリ バックエンドを作成するHow to: Create a .NET Mobile App backend

新しいプロジェクトを開始する場合は、 Azure Portal または Visual Studio を使用して、App Service アプリケーションを作成できます。If you are starting a new project, you can create an App Service application using either the Azure portal or Visual Studio. App Service アプリケーションをローカルで実行することも、プロジェクトをクラウドベースの App Service モバイル アプリに発行することもできます。You can run the App Service application locally or publish the project to your cloud-based App Service mobile app.

既存のプロジェクトにモバイル機能を追加する場合は、「 SDK をダウンロードして初期化する 」セクションを参照してください。If you are adding mobile capabilities to an existing project, see the Download and initialize the SDK section.

Azure ポータルで .NET バックエンドを作成するCreate a .NET backend using the Azure portal

App Service モバイル バックエンドを作成するには、クイックスタート チュートリアルまたは次の手順に従います。To create an App Service mobile backend, either follow the Quickstart tutorial or follow these steps:

  1. Azure Portal にサインインします。Sign in at the Azure portal.

  2. [+ 新規] > [Web + モバイル] > [モバイル アプリ] の順に選択し、Mobile Apps バックエンドの名前を入力します。Select +NEW > Web + Mobile > Mobile App, and then provide a name for your Mobile Apps back end.

  3. [リソース グループ] で、既存のリソース グループを選択するか、新しく作成します (アプリと同じ名前を使用)。For Resource Group, select an existing resource group, or create a new one (by using the same name as your app).

  4. [App Service プラン] では、既定のプラン (Standard レベル) が選択されています。For App Service plan, the default plan (in the Standard tier) is selected. 別のプランを選択することも、新しいプランを作成することもできます。You can also select a different plan, or create a new one.

    App Service プランの設定により、アプリに関連付けられる場所、機能、コスト、コンピューティング リソースが決まります。The App Service plan's settings determine the location, features, cost, and compute resources associated with your app. App Services プランの詳細と、さまざまな価格レベルおよび目的の場所で新しいプランを作成する方法については、「Azure App Service プランの概要」を参照してください。For more about App Service plans and how to create a new plan in a different pricing tier and in your desired location, see Azure App Service plans in-depth overview.

  5. 作成 を選択します。Select Create. この手順により、Mobile Apps バックエンドが作成されます。This step creates the Mobile Apps back end.

  6. 新しい Mobile Apps バックエンドの [設定] ウィンドウで、 [クイック スタート] > お使いのクライアント アプリ プラットフォーム > [データベースの接続] の順に選択します。In the Settings pane for the new Mobile Apps back end, select Quick start > your client app platform > Connect a database.

    データベース接続のための選択

  7. [データ接続の追加] ウィンドウで、 [SQL Database] > [新しいデータベースの作成] の順に選択します。In the Add data connection pane, select SQL Database > Create a new database. データベース名を入力し、価格レベルを選択して、 [サーバー] を選択します。Enter the database name, choose a pricing tier, and then select Server. この新しいデータベースは再利用できます。You can reuse this new database. 同じ場所に既にデータベースを所有している場合は、代わりに [既存のデータベースの使用] を選択することもできます。If you already have a database in the same location, you can instead choose Use an existing database. 別の場所にあるデータベースを使用することはお勧めしません。このようなデータベースを使用すると、帯域幅コストと待機時間が増加します。We don't recommend the use of a database in a different location, due to bandwidth costs and higher latency.

    データベースの選択

  8. [新しいサーバー] ウィンドウで、 [サーバー名] ボックスに一意のサーバー名を入力し、ログインとパスワードを指定して、 [Azure サービスにサーバーへのアクセスを許可する][OK] の順に選択します。In the New server pane, enter a unique server name in the Server name box, provide a login and password, select Allow Azure services to access server, and select OK. この手順により、新しいデータベースが作成されます。This step creates the new database.

  9. [データ接続の追加] ウィンドウに戻り、 [接続文字列] を選択し、データベースのログインとパスワードの値を入力して、 [OK] を選択します。Back in the Add data connection pane, select Connection string, enter the login and password values for your database, and select OK.

    データベースが正常にデプロイされるまで数分待ってから、次の手順に進んでください。Wait a few minutes for the database to be deployed successfully before you proceed.

[テーブル API の作成][はじめに] ブレードに戻り、 [バックエンド言語] として [C#] を選択します。Back in the Get started blade, under Create a table API, choose C# as your Backend language. [ダウンロード] をクリックし、圧縮されたプロジェクト ファイルをローカル コンピューターに抽出して、Visual Studio でソリューションを開きます。Click Download, extract the compressed project files to your local computer, and open the solution in Visual Studio.

Visual Studio 2017 を使用して .NET バックエンドを作成するCreate a .NET backend using Visual Studio 2017

Visual Studio インストーラーを使用して Azure ワークロードをインストールし、Visual Studio から Azure Mobile Apps プロジェクトに発行します。Install the Azure workload via the Visual Studio Installer to publish to Azure Mobile Apps project from Visual Studio. SDK のインストールが完了したら、次の手順を使用して ASP.NET アプリケーションを作成します。Once you have installed the SDK, create an ASP.NET application using the following steps:

  1. [新しいプロジェクト] ダイアログを開きます ( [ファイル] > [新規作成] > [プロジェクト...] の順にクリック)。Open the New Project dialog (from File > New > Project...).
  2. [Visual C#] を展開し、 [Web] を選択します。Expand Visual C# and select Web.
  3. [ASP.NET Web アプリケーション (.NET Framework)] を選択します。Select ASP.NET Web Application (.NET Framework).
  4. プロジェクト名を入力します。Fill in the project name. 次に、 [OK] をクリックしますThen click OK.
  5. テンプレートの一覧から [Azure Mobile App] を選択します。Select Azure Mobile App from the list of templates.
  6. [OK] をクリックしてソリューションを作成します。Click OK to create the solution.
  7. ソリューション エクスプローラーでプロジェクトを右クリックし、 [発行...] を選択し、発行のターゲットとして [App Service] を選択します。Right-click on the project in the Solution Explorer and choose Publish..., then choose App Service as the publishing target.
  8. プロンプトに従って認証し、発行する新規または既存の Azure App Service を選択します。Follow the prompts to authenticate and choose a new or existing Azure App Service to publish.

Visual Studio 2015 を使用して .NET バックエンドを作成するCreate a .NET backend using Visual Studio 2015

Visual Studio で Azure Mobile Apps プロジェクトを作成するには、Azure SDK for .NET (バージョン 2.9.0 以降) をインストールします。Install the Azure SDK for .NET (version 2.9.0 or later) to create an Azure Mobile Apps project in Visual Studio. SDK のインストールが完了したら、次の手順を使用して ASP.NET アプリケーションを作成します。Once you have installed the SDK, create an ASP.NET application using the following steps:

  1. [新しいプロジェクト] ダイアログを開きます ( [ファイル] > [新規作成] > [プロジェクト...] の順にクリック)。Open the New Project dialog (from File > New > Project...).
  2. [テンプレート] > [Visual C#] の順に展開し、 [Web] を選択します。Expand Templates > Visual C#, and select Web.
  3. [ASP.NET Web アプリケーション] を選択します。Select ASP.NET Web Application.
  4. プロジェクト名を入力します。Fill in the project name. 次に、 [OK] をクリックしますThen click OK.
  5. ASP.NET 4.5.2 テンプレート[Azure Mobile App] を選択します。Under ASP.NET 4.5.2 Templates, select Azure Mobile App. このプロジェクトの発行先となるクラウドにモバイル バックエンドを作成するために、 [Host in the cloud (クラウドにホストする)] チェック ボックスをオンにします。Check Host in the cloud to create a mobile backend in the cloud to which you can publish this project.
  6. Click OK.Click OK.

方法:SDK をダウンロードして初期化するHow to: Download and initialize the SDK

SDK は NuGet.orgで入手できます。このパッケージには、SDK の使用を開始するために必要な基礎機能が含まれています。The SDK is available on NuGet.org. This package includes the base functionality required to get started using the SDK. SDK を初期化するには、 HttpConfiguration オブジェクトに対して操作を実行する必要があります。To initialize the SDK, you need to perform actions on the HttpConfiguration object.

SDK のインストールInstall the SDK

SDK をインストールするには、Visual Studio でサーバー プロジェクトを右クリックして [NuGet パッケージの管理] を選択し、Microsoft.Azure.Mobile.Server パッケージを検索してから、 [インストール] をクリックします。To install the SDK, right-click on the server project in Visual Studio, select Manage NuGet Packages, search for the Microsoft.Azure.Mobile.Server package, then click Install.

サーバー プロジェクトの初期化Initialize the server project

.NET バックエンド サーバー プロジェクトは、他の ASP.NET プロジェクトと同じように、OWIN スタートアップ クラスを組み込むことによって初期化します。A .NET backend server project is initialized similar to other ASP.NET projects, by including an OWIN startup class. NuGet パッケージ Microsoft.Owin.Host.SystemWebが参照されていることを確認します。Ensure that you have referenced the NuGet package Microsoft.Owin.Host.SystemWeb. Visual Studio でこのクラスを追加するには、サーバー プロジェクトを右クリックして、 [追加] > [新しい項目][Web] > [全般] > [OWIN スタートアップ クラス] の順に選択します。To add this class in Visual Studio, right-click on your server project and select Add > New Item, then Web > General > OWIN Startup class. 次の属性を持つクラスが生成されます。A class is generated with the following attribute:

[assembly: OwinStartup(typeof(YourServiceName.YourStartupClassName))]

OWIN スタートアップ クラスの Configuration() メソッドで、 HttpConfiguration オブジェクトを使用して Azure Mobile Apps 環境を構成します。In the Configuration() method of your OWIN startup class, use an HttpConfiguration object to configure the Azure Mobile Apps environment. 次の例では、機能を追加せずにサーバー プロジェクトを初期化します。The following example initializes the server project with no added features:

// in OWIN startup class
public void Configuration(IAppBuilder app)
{
    HttpConfiguration config = new HttpConfiguration();

    new MobileAppConfiguration()
        // no added features
        .ApplyTo(config);

    app.UseWebApi(config);
}

個別の機能を有効化するには、ApplyTo を呼び出す前に、MobileAppConfiguration オブジェクトに対して拡張機能メソッドを呼び出す必要があります。To enable individual features, you must call extension methods on the MobileAppConfiguration object before calling ApplyTo. たとえば、次のコードでは、初期化中に [MobileAppController] 属性が設定されているすべての API コントローラーに既定のルートを追加します。For example, the following code adds the default routes to all API controllers that have the attribute [MobileAppController] during initialization:

new MobileAppConfiguration()
    .MapApiControllers()
    .ApplyTo(config);

Azure ポータルからのサーバーのクイックスタートは UseDefaultConfiguration() を呼び出します。The server quickstart from the Azure portal calls UseDefaultConfiguration(). これは次のセットアップと同等です。This equivalent to the following setup:

    new MobileAppConfiguration()
        .AddMobileAppHomeController()             // from the Home package
        .MapApiControllers()
        .AddTables(                               // from the Tables package
            new MobileAppTableConfiguration()
                .MapTableControllers()
                .AddEntityFramework()             // from the Entity package
            )
        .AddPushNotifications()                   // from the Notifications package
        .MapLegacyCrossDomainController()         // from the CrossDomain package
        .ApplyTo(config);

使用する拡張メソッドは次のとおりです。The extension methods used are:

  • AddMobileAppHomeController() は、既定の Azure Mobile Apps ホーム ページを提供します。AddMobileAppHomeController() provides the default Azure Mobile Apps home page.
  • MapApiControllers() は、[MobileAppController] 属性で修飾された WebAPI コントローラーのカスタム API 機能を提供します。MapApiControllers() provides custom API capabilities for WebAPI controllers decorated with the [MobileAppController] attribute.
  • AddTables() は、テーブル コントローラーへの /tables エンドポイントのマッピングを提供します。AddTables() provides a mapping of the /tables endpoints to table controllers.
  • AddTablesWithEntityFramework() は、Entity Framework ベースのコントローラーを使用して /tables エンドポイントをマッピングするための簡単な方法です。AddTablesWithEntityFramework() is a short-hand for mapping the /tables endpoints using Entity Framework based controllers.
  • AddPushNotifications() を使用すると、Notification Hubs 用のデバイスを簡単に登録できます。AddPushNotifications() provides a simple method of registering devices for Notification Hubs.
  • MapLegacyCrossDomainController() は、ローカル開発のための標準 CORS ヘッダーを提供します。MapLegacyCrossDomainController() provides standard CORS headers for local development.

SDK 拡張機能SDK extensions

次の NuGet ベースの拡張機能パッケージでは、アプリケーションで使用可能な各種モバイル機能が提供されます。The following NuGet-based extension packages provide various mobile features that can be used by your application. 拡張機能の有効化は、初期化中に MobileAppConfiguration オブジェクトを使用して行います。You enable extensions during initialization by using the MobileAppConfiguration object.

  • Microsoft.Azure.Mobile.Server.Quickstart Mobile Apps の基本的なセットアップをサポートします。Microsoft.Azure.Mobile.Server.Quickstart Supports the basic Mobile Apps setup. 構成に追加するには、初期化中に UseDefaultConfiguration 拡張機能メソッドを呼び出します。Added to the configuration by calling the UseDefaultConfiguration extension method during initialization. この拡張機能には、次の拡張機能が含まれています。Notifications、Authentication、Entity、Tables、Cross-domain、および Home パッケージ。This extension includes following extensions: Notifications, Authentication, Entity, Tables, Cross-domain, and Home packages. このパッケージは、Azure Portal で利用可能な Mobile Apps クイック スタートで使用されます。This package is used by the Mobile Apps Quickstart available on the Azure portal.
  • Microsoft.Azure.Mobile.Server.Home Web サイトのルートに、 このモバイル アプリが実行される既定のページ を実装します。Microsoft.Azure.Mobile.Server.Home Implements the default this mobile app is up and running page for the web site root. 構成に追加するには、 AddMobileAppHomeController 拡張メソッドを呼び出します。Add to the configuration by calling the AddMobileAppHomeController extension method.
  • Microsoft.Azure.Mobile.Server.Tables データ処理のためのクラスが含まれており、データ パイプラインを設定します。Microsoft.Azure.Mobile.Server.Tables includes classes for working with data and sets-up the data pipeline. 構成に追加するには、 AddTables 拡張メソッドを呼び出します。Add to the configuration by calling the AddTables extension method.
  • Microsoft.Azure.Mobile.Server.Entity Entity Framework で SQL Database のデータにアクセスできるようにします。Microsoft.Azure.Mobile.Server.Entity Enables the Entity Framework to access data in the SQL Database. 構成に追加するには、 AddTablesWithEntityFramework 拡張メソッドを呼び出します。Add to the configuration by calling the AddTablesWithEntityFramework extension method.
  • Microsoft.Azure.Mobile.Server.Authentication 認証を有効にし、トークンの検証に使用する OWIN ミドルウェアを設定します。Microsoft.Azure.Mobile.Server.Authentication Enables authentication and sets-up the OWIN middleware used to validate tokens. 構成に追加するには、AddAppServiceAuthentication 拡張メソッドと IAppBuilder.UseAppServiceAuthentication 拡張メソッドを呼び出します。Add to the configuration by calling the AddAppServiceAuthentication and IAppBuilder.UseAppServiceAuthentication extension methods.
  • Microsoft.Azure.Mobile.Server.Notifications プッシュ通知を有効にし、プッシュ登録エンドポイントを定義します。Microsoft.Azure.Mobile.Server.Notifications Enables push notifications and defines a push registration endpoint. 構成に追加するには、 AddPushNotifications 拡張メソッドを呼び出します。Add to the configuration by calling the AddPushNotifications extension method.
  • Microsoft.Azure.Mobile.Server.CrossDomain モバイル アプリから従来の Web ブラウザーにデータを提供するコントローラーを作成します。Microsoft.Azure.Mobile.Server.CrossDomain Creates a controller that serves data to legacy web browsers from your Mobile App. 構成に追加するには、 MapLegacyCrossDomainController 拡張メソッドを呼び出します。Add to the configuration by calling the MapLegacyCrossDomainController extension method.
  • Microsoft.Azure.Mobile.Server.Login カスタム認証シナリオで使用される静的メソッドである AppServiceLoginHandler.CreateToken() メソッドを提供します。Microsoft.Azure.Mobile.Server.Login Provides the AppServiceLoginHandler.CreateToken() method, which is a static method used during custom authentication scenarios.

方法:サーバー プロジェクトを発行するHow to: Publish the server project

このセクションでは、Visual Studio から .NET バックエンド プロジェクトを発行する方法を示します。This section shows you how to publish your .NET backend project from Visual Studio. Git やその他の利用可能な方法を利用して、バックエンド プロジェクトをデプロイすることもできます。You can also deploy your backend project using Git or any of the other methods available there.

  1. Visual Studio でプロジェクトをリビルドして、NuGet パッケージを復元します。In Visual Studio, rebuild the project to restore NuGet packages.

  2. ソリューション エクスプローラーで目的のプロジェクトを右クリックし、 [発行] をクリックします。In Solution Explorer, right-click the project, click Publish. 初めて発行するときには、発行プロファイルを定義する必要があります。The first time you publish, you need to define a publishing profile. 既に定義したプロファイルがある場合は、それを選択し、 [発行] をクリックします。When you already have a profile defined, you can select it and click Publish.

  3. 発行先の選択を求められた場合は、 [Microsoft Azure App Service] > [次へ] の順にクリックして、必要であれば Azure の資格情報でサインインします。If asked to select a publish target, click Microsoft Azure App Service > Next, then (if needed) sign-in with your Azure credentials. Visual Studio によって Azure から発行設定が直接ダウンロードされ、安全に保存されます。Visual Studio downloads and securely stores your publish settings directly from Azure.

  4. サブスクリプションを選択し、 [表示][リソースの種類] を選択して、 [モバイル アプリ] を展開します。次に、モバイル アプリ バックエンドをクリックし、 [OK] をクリックします。Choose your Subscription, select Resource Type from View, expand Mobile App, and click your Mobile App backend, then click OK.

  5. 発行プロファイル情報を確認し、 [発行] をクリックします。Verify the publish profile information and click Publish.

    モバイル アプリ バックエンドが正常に発行されると、そのことを示すランディング ページが表示されます。When your Mobile App backend has published successfully, you see a landing page indicating success.

方法:テーブル コントローラーを定義するHow to: Define a table controller

SQL テーブルをモバイル クライアントに公開するためのテーブル コントローラーを定義します。Define a Table Controller to expose a SQL table to mobile clients. テーブル コントローラーを構成するには、3 つの手順が必要です。Configuring a Table Controller requires three steps:

  1. データ転送オブジェクト (DTO) クラスを作成する。Create a Data Transfer Object (DTO) class.
  2. Mobile DbContext クラスにテーブル参照を構成する。Configure a table reference in the Mobile DbContext class.
  3. テーブル コントローラーを作成する。Create a table controller.

データ転送オブジェクト (DTO) は、 EntityDataから継承するプレーンな C# オブジェクトです。A Data Transfer Object (DTO) is a plain C# object that inherits from EntityData. 例:For example:

public class TodoItem : EntityData
{
    public string Text { get; set; }
    public bool Complete {get; set;}
}

DTO を使用して、SQL データベース内にテーブルを定義します。The DTO is used to define the table within the SQL database. データベース エントリを作成するには、使用している DbContext に DbSet<> プロパティを追加します。To create the database entry, add a DbSet<> property to the DbContext you are using. Azure Mobile Apps の既定のプロジェクト テンプレートでは、DbContext が Models\MobileServiceContext.csと記述されています。In the default project template for Azure Mobile Apps, the DbContext is called Models\MobileServiceContext.cs:

public class MobileServiceContext : DbContext
{
    private const string connectionStringName = "Name=MS_TableConnectionString";

    public MobileServiceContext() : base(connectionStringName)
    {

    }

    public DbSet<TodoItem> TodoItems { get; set; }

    protected override void OnModelCreating(DbModelBuilder modelBuilder)
    {
        modelBuilder.Conventions.Add(
            new AttributeToColumnAnnotationConvention<TableColumnAttribute, string>(
                "ServiceColumnTable", (property, attributes) => attributes.Single().ColumnType.ToString()));
    }
}

Azure SDK をインストール済みの場合は、テンプレート テーブル コントローラーを次のように作成できます。If you have the Azure SDK installed, you can now create a template table controller as follows:

  1. Controllers フォルダーを右クリックし、 [追加] > [コントローラー] 」を参照してください。Right-click on the Controllers folder and select Add > Controller....
  2. [Azure Mobile Apps のテーブル コントローラー] オプションを選択し、 [追加] をクリックします。Select the Azure Mobile Apps Table Controller option, then click Add.
  3. [コントローラーの追加] ダイアログ ボックスで、次の手順を実行します。In the Add Controller dialog:
    • [モデル クラス] ボックスの一覧で、新しい DTO を選択します。In the Model class dropdown, select your new DTO.
    • [DbContext] ボックスの一覧で、モバイル サービス DbContext クラスを選択します。In the DbContext dropdown, select the Mobile Service DbContext class.
    • コントローラー名は自動的に作成されます。The Controller name is created for you.
  4. [追加] をクリックします。Click Add.

クイックスタート サーバー プロジェクトには、シンプルな TodoItemControllerの例が含まれています。The quickstart server project contains an example for a simple TodoItemController.

方法:テーブルのページング サイズを調整するHow to: Adjust the table paging size

既定では、Azure Mobile Apps は、要求ごとに 50 個のレコードを返します。By default, Azure Mobile Apps returns 50 records per request. ページングにより、クライアントが長期間 UI スレッドまたはサーバーを占有することがなくなるため、優れたユーザー エクスペリエンスが保証されます。Paging ensures that the client does not tie up their UI thread nor the server for too long, ensuring a good user experience. テーブルのページング サイズを変更するには、サーバー側の "許可されているクエリ サイズ" とクライアント側のページ サイズを大きくします。サーバー側の "許可されているクエリ サイズ" は、EnableQuery 属性を使用して調整します。To change the table paging size, increase the server side "allowed query size" and the client-side page size The server side "allowed query size" is adjusted using the EnableQuery attribute:

[EnableQuery(PageSize = 500)]

PageSize が、クライアントから要求されるサイズ以上になるようにしてください。Ensure the PageSize is the same or larger than the size requested by the client. クライアントのページ サイズを変更する方法の詳細については、特定のクライアントのハウツー ドキュメントを参照してください。Refer to the specific client HOWTO documentation for details on changing the client page size.

方法:カスタム API コントローラーを定義するHow to: Define a custom API controller

カスタム API コントローラーは、エンドポイントを公開して、モバイル アプリのバックエンドに最も基本的な機能を提供します。The custom API controller provides the most basic functionality to your Mobile App backend by exposing an endpoint. [MobileAppController] 属性を使用して、モバイル固有の API コント ローラーを登録できます。You can register a mobile-specific API controller using the [MobileAppController] attribute. MobileAppController 属性は、ルートを登録し、Mobile Apps JSON シリアライザーを設定するほか、 クライアント バージョン チェックをオンにします。The MobileAppController attribute registers the route, sets up the Mobile Apps JSON serializer, and turns on client version checking.

  1. Visual Studio で、Controllers フォルダーを右クリックして、 [追加] > [コントローラー] の順にクリックし、 [Web API 2 コントローラー — 空] を選択して [追加] をクリックします。In Visual Studio, right-click the Controllers folder, then click Add > Controller, select Web API 2 Controller—Empty and click Add.

  2. コントローラー名 (CustomController など) を指定し、 [追加] をクリックします。Supply a Controller name, such as CustomController, and click Add.

  3. 新しいコントローラーのクラス ファイルに、次の using ステートメントを追加します。In the new controller class file, add the following using statement:

     using Microsoft.Azure.Mobile.Server.Config;
    
  4. 次の例に従って、API コントローラーのクラス定義に [MobileAppController] 属性を適用します。Apply the [MobileAppController] attribute to the API controller class definition, as in the following example:

     [MobileAppController]
     public class CustomController : ApiController
     {
           //...
     }
    
  5. 次の例に示すように、App_Start/Startup.MobileApp.cs ファイルに MapApiControllers 拡張メソッドの呼び出しを追加します。In App_Start/Startup.MobileApp.cs file, add a call to the MapApiControllers extension method, as in the following example:

     new MobileAppConfiguration()
         .MapApiControllers()
         .ApplyTo(config);
    

MapApiControllers() の代わりに UseDefaultConfiguration() 拡張メソッドを使用することもできます。You can also use the UseDefaultConfiguration() extension method instead of MapApiControllers(). クライアントは MobileAppControllerAttribute が適用されていないコントローラーにもアクセスできますが、こうしたコントローラーはモバイル アプリ クライアント SDK を使用するクライアントでは適切に使用されない場合があります。Any controller that does not have MobileAppControllerAttribute applied can still be accessed by clients, but it may not be correctly consumed by clients using any Mobile App client SDK.

方法:認証を操作するHow to: Work with authentication

Azure Mobile Apps は、App Service 認証/承認を使用してモバイル バックエンドをセキュリティで保護します。Azure Mobile Apps uses App Service Authentication / Authorization to secure your mobile backend. このセクションでは、.NET バックエンド サーバー プロジェクトで以下の認証関連のタスクを実行する方法を説明します。This section shows you how to perform the following authentication-related tasks in your .NET backend server project:

方法:サーバー プロジェクトに認証を追加するHow to: Add authentication to a server project

MobileAppConfiguration オブジェクトを拡張し、OWIN ミドルウェアを構成すると、サーバー プロジェクトに認証を追加することができます。You can add authentication to your server project by extending the MobileAppConfiguration object and configuring OWIN middleware. Microsoft.Azure.Mobile.Server.Quickstart パッケージをインストールし、 UseDefaultConfiguration 拡張メソッドを呼び出している場合は、手順 3 に進むことができます。When you install the Microsoft.Azure.Mobile.Server.Quickstart package and call the UseDefaultConfiguration extension method, you can skip to step 3.

  1. Visual Studio で、 Microsoft.Azure.Mobile.Server.Authentication パッケージをインストールします。In Visual Studio, install the Microsoft.Azure.Mobile.Server.Authentication package.

  2. Startup.cs プロジェクト ファイルで、 Configuration メソッドの先頭に次のコード行を追加します。In the Startup.cs project file, add the following line of code at the beginning of the Configuration method:

     app.UseAppServiceAuthentication(config);
    

    この OWIN ミドルウェア コンポーネントは、関連付けられている App Service ゲートウェイによって発行されたトークンを検証します。This OWIN middleware component validates tokens issued by the associated App Service gateway.

  3. 認証が必要なすべてのコントローラーまたはメソッドに [Authorize] 属性を追加します。Add the [Authorize] attribute to any controller or method that requires authentication.

Mobile Apps バックエンドに対してクライアントを認証する方法については、「 アプリケーションに認証を追加する」をご覧ください。To learn about how to authenticate clients to your Mobile Apps backend, see Add authentication to your app.

方法:アプリケーションにカスタム認証を使用するHow to: Use custom authentication for your application

重要

カスタム認証を有効にするには、まず、Azure Portal で App Service のプロバイダーを選択せずに App Service 認証を有効にする必要があります。In order to enable custom authentication, you must first enable App Service Authentication without selecting a provider for your App Service in the Azure portal. ホストされている場合は、これにより WEBSITE_AUTH_SIGNING_KEY 環境変数が有効になります。This will enable the WEBSITE_AUTH_SIGNING_KEY environment variable when hosted.

App Service 認証/承認プロバイダーの中に使用したいものがない場合は、独自のログイン システムを実装できます。If you do not wish to use one of the App Service Authentication/Authorization providers, you can implement your own login system. 認証トークンの生成に役立つ Microsoft.Azure.Mobile.Server.Login パッケージをインストールします。Install the Microsoft.Azure.Mobile.Server.Login package to assist with authentication token generation. ユーザー資格情報を検証するための独自のコードを指定します。Provide your own code for validating user credentials. たとえば、データベース内のソルトを使用してハッシュ化されたパスワードと照合することができます。For example, you might check against salted and hashed passwords in a database. 次の例では、(他の場所に定義されている) isValidAssertion() メソッドがこれらの照合を実行します。In the example below, the isValidAssertion() method (defined elsewhere) is responsible for these checks.

カスタム認証を公開するには、ApiController を作成し、register アクションと login アクションを公開します。The custom authentication is exposed by creating an ApiController and exposing register and login actions. クライアントは、カスタム UI を使用してユーザーから情報を収集する必要があります。The client should use a custom UI to collect the information from the user. その後、この情報は、標準の HTTP POST 呼び出しで API に送信されます。The information is then submitted to the API with a standard HTTP POST call. サーバーでアサーションを検証したら、 AppServiceLoginHandler.CreateToken() メソッドを使用してトークンを発行します。Once the server validates the assertion, a token is issued using the AppServiceLoginHandler.CreateToken() method. ApiController で [MobileAppController] 属性を使用することはできませんThe ApiController should not use the [MobileAppController] attribute.

login アクションの例:An example login action:

    public IHttpActionResult Post([FromBody] JObject assertion)
    {
        if (isValidAssertion(assertion)) // user-defined function, checks against a database
        {
            JwtSecurityToken token = AppServiceLoginHandler.CreateToken(new Claim[] { new Claim(JwtRegisteredClaimNames.Sub, assertion["username"]) },
                mySigningKey,
                myAppURL,
                myAppURL,
                TimeSpan.FromHours(24) );
            return Ok(new LoginResult()
            {
                AuthenticationToken = token.RawData,
                User = new LoginResultUser() { UserId = userName.ToString() }
            });
        }
        else // user assertion was not valid
        {
            return this.Request.CreateUnauthorizedResponse();
        }
    }

前の例の LoginResult と LoginResultUser は、必要なプロパティを公開する、シリアル化可能なオブジェクトです。In the preceding example, LoginResult and LoginResultUser are serializable objects exposing required properties. クライアントでは、ログインの応答が次の形式の JSON オブジェクトとして返されるものと想定されています。The client expects login responses to be returned as JSON objects of the form:

    {
        "authenticationToken": "<token>",
        "user": {
            "userId": "<userId>"
        }
    }

AppServiceLoginHandler.CreateToken() メソッドには、audience パラメーターと issuer パラメーターが含まれています。The AppServiceLoginHandler.CreateToken() method includes an audience and an issuer parameter. どちらのパラメーターも、HTTPS スキームを使用してアプリケーション ルートの URL に設定します。Both of these parameters are set to the URL of your application root, using the HTTPS scheme. 同様に、secretKey をアプリケーションの署名キーの値に設定する必要があります。Similarly you should set secretKey to be the value of your application's signing key. キーを生成してユーザーを偽装するために使用される可能性があるため、クライアントで署名キーを配布しないでください。Do not distribute the signing key in a client as it can be used to mint keys and impersonate users. App Service でホストされているときに署名キーを取得するには、WEBSITE_AUTH_SIGNING_KEY 環境変数を参照します。You can obtain the signing key while hosted in App Service by referencing the WEBSITE_AUTH_SIGNING_KEY environment variable. ローカル デバッグの実行で必要な場合は、「 認証に関するローカル デバッグ 」セクションの手順に従ってキーを取得し、アプリケーション設定として保存します。If needed in a local debugging context, follow the instructions in the Local debugging with authentication section to retrieve the key and store it as an application setting.

また、発行されたトークンには、他の要求および有効期限を含めることもできます。The issued token may also include other claims and an expiry date. 少なくとも、発行されたトークンには、サブジェクト (sub) 要求が含まれている必要があります。Minimally, the issued token must include a subject (sub) claim.

認証ルートをオーバーロードすることにより、標準クライアント loginAsync() メソッドをサポートできます。You can support the standard client loginAsync() method by overloading the authentication route. クライアントが client.loginAsync('custom'); を呼び出してログインする場合、ルートは /.auth/login/custom である必要があります。If the client calls client.loginAsync('custom'); to log in, your route must be /.auth/login/custom. カスタム認証コントローラーのルートは、 MapHttpRoute()を使用して設定できます。You can set the route for the custom authentication controller using MapHttpRoute():

config.Routes.MapHttpRoute("custom", ".auth/login/custom", new { controller = "CustomAuth" });

ヒント

loginAsync() アプローチを使用すると、後続のサービスのすべての呼び出しに認証トークンが添付されます。Using the loginAsync() approach ensures that the authentication token is attached to every subsequent call to the service.

方法:認証されたユーザー情報を取得するHow to: Retrieve authenticated user information

ユーザーが App Service によって認証されると、.NET バックエンド コードで、割り当てられたユーザー ID とその他の情報にアクセスできます。When a user is authenticated by App Service, you can access the assigned user ID and other information in your .NET backend code. このユーザー情報を使用して、バックエンドで承認の決定を行うことができます。The user information can be used for making authorization decisions in the backend. 次のコードは、要求に関連付けられているユーザー ID を取得します。The following code obtains the user ID associated with a request:

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

SID はプロバイダー固有のユーザー ID から派生し、特定のユーザーとログイン プロバイダーに対して静的です。The SID is derived from the provider-specific user ID and is static for a given user and login provider. 無効な認証トークンの SID は null です。The SID is null for invalid authentication tokens.

App Service では、ログイン プロバイダーからの特定の要求を行うこともできます。App Service also lets you request specific claims from your login provider. 各 ID プロバイダーは、ID プロバイダー SDK を使用してさらに多くの情報を提供できます。Each identity provider can provide more information using the identity provider SDK. たとえば、友人の情報については Facebook Graph API を使用できます。For example, you can use the Facebook Graph API for friends information. Azure Portal のプロバイダー ブレードで、要求された要求を指定できます。You can specify claims that are requested in the provider blade in the Azure portal. 要求によっては、ID プロバイダーの追加の構成が必要です。Some claims require additional configuration with the identity provider.

次のコードは、GetAppServiceIdentityAsync 拡張メソッドを呼び出して、ログイン資格情報を取得します。この情報には、Facebook Graph API に対する要求を行うために必要なアクセス トークンが含まれています。The following code calls the GetAppServiceIdentityAsync extension method to get the login credentials, which include the access token needed to make requests against the Facebook Graph API:

// Get the credentials for the logged-in user.
var credentials =
    await this.User
    .GetAppServiceIdentityAsync<FacebookCredentials>(this.Request);

if (credentials.Provider == "Facebook")
{
    // Create a query string with the Facebook access token.
    var fbRequestUrl = "https://graph.facebook.com/me/feed?access_token="
        + credentials.AccessToken;

    // Create an HttpClient request.
    var client = new System.Net.Http.HttpClient();

    // Request the current user info from Facebook.
    var resp = await client.GetAsync(fbRequestUrl);
    resp.EnsureSuccessStatusCode();

    // Do something here with the Facebook user information.
    var fbInfo = await resp.Content.ReadAsStringAsync();
}

GetAppServiceIdentityAsync 拡張メソッドを提供するには、System.Security.Principal の using ステートメントを追加します。Add a using statement for System.Security.Principal to provide the GetAppServiceIdentityAsync extension method.

方法:承認されたユーザーに対するデータ アクセスを制限するHow to: Restrict data access for authorized users

前のセクションでは、認証されたユーザーのユーザー ID を取得する方法について説明しました。In the previous section, we showed how to retrieve the user ID of an authenticated user. この値に基づいて、データとその他のリソースへのアクセスを制限できます。You can restrict access to data and other resources based on this value. たとえば、UserId 列をテーブルに追加して、ユーザー ID によってクエリの結果をフィルター処理すると、承認されたユーザーだけにデータが返されるように簡単に制限できます。For example, adding a userId column to tables and filtering the query results by the user ID is a simple way to limit returned data only to authorized users. 次のコードは、SID が TodoItem テーブルの UserId 列の値と一致する場合にのみデータ行を返します。The following code returns data rows only when the SID matches the value in the UserId column on the TodoItem table:

// Get the SID of the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;

// Only return data rows that belong to the current user.
return Query().Where(t => t.UserId == sid);

Query() メソッドは、フィルター処理を行うために LINQ で操作できる IQueryable を返します。The Query() method returns an IQueryable that can be manipulated by LINQ to handle filtering.

方法:サーバー プロジェクトにプッシュ通知を追加するHow to: Add push notifications to a server project

MobileAppConfiguration オブジェクトを拡張し、Notification Hubs クライアントを作成して、サーバー プロジェクトにプッシュ通知を追加します。Add push notifications to your server project by extending the MobileAppConfiguration object and creating a Notification Hubs client.

  1. Visual Studio でサーバー プロジェクトを右クリックし、 [NuGet パッケージの管理] をクリックして Microsoft.Azure.Mobile.Server.Notifications を見つけ、 [インストール] をクリックします。In Visual Studio, right-click the server project and click Manage NuGet Packages, search for Microsoft.Azure.Mobile.Server.Notifications, then click Install.

  2. 上記の手順を繰り返して、Notification Hubs クライアント ライブラリが含まれる Microsoft.Azure.NotificationHubs パッケージをインストールします。Repeat this step to install the Microsoft.Azure.NotificationHubs package, which includes the Notification Hubs client library.

  3. App_Start/Startup.MobileApp.cs で、初期化中に AddPushNotifications() 拡張メソッドの呼び出しを追加します。In App_Start/Startup.MobileApp.cs, and add a call to the AddPushNotifications() extension method during initialization:

     new MobileAppConfiguration()
         // other features...
         .AddPushNotifications()
         .ApplyTo(config);
    
  4. Notification Hubs クライアントを作成する次のコードを追加します。Add the following code that creates a Notification Hubs client:

     // Get the settings for the server project.
     HttpConfiguration config = this.Configuration;
     MobileAppSettingsDictionary settings =
         config.GetMobileAppSettingsProvider().GetMobileAppSettings();
    
     // Get the Notification Hubs credentials for the Mobile App.
     string notificationHubName = settings.NotificationHubName;
     string notificationHubConnection = settings
         .Connections[MobileAppSettingsKeys.NotificationHubConnectionString].ConnectionString;
    
     // Create a new Notification Hub client.
     NotificationHubClient hub = NotificationHubClient
         .CreateClientFromConnectionString(notificationHubConnection, notificationHubName);
    

これで、Notification Hubs クライアントを使用して、登録済みデバイスにプッシュ通知を送信できるようになりました。You can now use the Notification Hubs client to send push notifications to registered devices. 詳細については、「 アプリケーションにプッシュ通知を追加する」をご覧ください。For more information, see Add push notifications to your app. Notification Hubs の詳細については、 Notification Hubs の概要に関するページを参照してください。To learn more about Notification Hubs, see Notification Hubs Overview.

方法:タグを使用してターゲット プッシュを有効にするHow to: Enable targeted push using Tags

Notification Hubs では、タグを使用して、ターゲットを絞った通知を特定の登録に送信できます。Notification Hubs lets you send targeted notifications to specific registrations by using tags. いくつかのタグは自動的に作成されます。Several tags are created automatically:

  • インストール ID は、特定のデバイスを識別します。The Installation ID identifies a specific device.
  • 認証済みの SID に基づくユーザー ID は、特定のユーザーを識別します。The User Id based on the authenticated SID identifies a specific user.

インストール ID には、MobileServiceClientinstallationId プロパティからアクセスできます。The installation ID can be accessed from the installationId property on the MobileServiceClient. 次の例では、Notification Hubs でインストール ID を使用して特定のインストールにタグを追加する方法を示します。The following example shows how to use an installation ID to add a tag to a specific installation in Notification Hubs:

hub.PatchInstallation("my-installation-id", new[]
{
    new PartialUpdateOperation
    {
        Operation = UpdateOperationType.Add,
        Path = "/tags",
        Value = "{my-tag}"
    }
});

インストールを作成するときは、プッシュ通知の登録時にクライアントから提供されたタグはすべてバックエンドで無視されます。Any tags supplied by the client during push notification registration are ignored by the backend when creating the installation. クライアントがインストールにタグを追加できるようにするには、前述のパターンを使用してタグを追加するカスタム API を作成する必要があります。To enable a client to add tags to the installation, you must create a custom API that adds tags using the preceding pattern.

例については、App Service Mobile Apps の完成したクイックスタート サンプルのクライアントによって追加されるプッシュ通知タグに関するセクションを参照してください。See Client-added push notification tags in the App Service Mobile Apps completed quickstart sample for an example.

方法:認証されたユーザーにプッシュ通知を送信するHow to: Send push notifications to an authenticated user

認証済みのユーザーがプッシュ通知に登録すると、ユーザー ID タグが登録に自動的に追加されます。When an authenticated user registers for push notifications, a user ID tag is automatically added to the registration. このタグを使用すると、そのユーザーが登録したすべてのデバイスにプッシュ通知を送信できます。By using this tag, you can send push notifications to all devices registered by that person. 次のコードでは、要求を行ったユーザーの SID を取得し、そのユーザーのすべてのデバイス登録にテンプレート プッシュ通知を送信します。The following code gets the SID of user making the request and sends a template push notification to every device registration for that person:

// Get the current user SID and create a tag for the current user.
var claimsPrincipal = this.User as ClaimsPrincipal;
string sid = claimsPrincipal.FindFirst(ClaimTypes.NameIdentifier).Value;
string userTag = "_UserId:" + sid;

// Build a dictionary for the template with the item message text.
var notification = new Dictionary<string, string> { { "message", item.Text } };

// Send a template notification to the user ID.
await hub.SendTemplateNotificationAsync(notification, userTag);

認証されたクライアントからプッシュ通知を登録する場合は、登録を試みる前に、認証が完了していることを確認します。When registering for push notifications from an authenticated client, make sure that authentication is complete before attempting registration. 詳細については、「.NET バックエンド向けの App Service Mobile Apps の完成したクイックスタート サンプル」の「ユーザーへのプッシュ」をご覧ください。For more information, see Push to users in the App Service Mobile Apps completed quickstart sample for .NET backend.

方法:.NET サーバー SDK のデバッグとトラブルシューティングを実行するHow to: Debug and troubleshoot the .NET Server SDK

Azure App Service には、ASP.NET アプリケーションのデバッグとトラブルシューティングの方法が複数用意されています。Azure App Service provides several debugging and troubleshooting techniques for ASP.NET applications:

ログの記録Logging

標準の ASP.NET トレース書き込みを使用して、App Service の診断ログを作成できます。You can write to App Service diagnostic logs by using the standard ASP.NET trace writing. ログに書き込めるようにするには、モバイル アプリ バックエンドで診断を有効にする必要があります。Before you can write to the logs, you must enable diagnostics in your Mobile App backend.

診断を有効にしてログに書き込むには、次の手順を実行します。To enable diagnostics and write to the logs:

  1. アプリケーションのログ記録を有効にする (Windows)」の手順に従います。Follow the steps in Enable application logging (Windows).

  2. 次の using ステートメントをコード ファイルに追加します。Add the following using statement in your code file:

     using System.Web.Http.Tracing;
    
  3. .NET バックエンドから診断ログに書き込むために、次のようにトレース ライターを作成します。Create a trace writer to write from the .NET backend to the diagnostic logs, as follows:

     ITraceWriter traceWriter = this.Configuration.Services.GetTraceWriter();
     traceWriter.Info("Hello, World");
    
  4. サーバー プロジェクトを再発行し、モバイル アプリ バックエンドにアクセスして、ログ記録付きでコード パスを実行します。Republish your server project, and access the Mobile App backend to execute the code path with the logging.

  5. ログ ファイルにアクセスする」で説明されているように、ログをダウンロードして評価します。Download and evaluate the logs, as described in Access log files.

認証に関するローカル デバッグLocal debugging with authentication

クラウドに発行する前に変更をテストするために、ローカルでアプリケーションを実行できます。You can run your application locally to test changes before publishing them to the cloud. ほとんどの Azure Mobile Apps バックエンドでは、Visual Studio で F5 キーを押します。For most Azure Mobile Apps backends, press F5 while in Visual Studio. ただし、認証を使用している場合は追加の考慮事項がいくつかあります。However, there are some additional considerations when using authentication.

App Service Authentication/Authorization を使用してクラウド ベースのモバイル アプリを構成する必要があります。また、クライアントに代替ログイン ホストとしてクラウド エンドポイントを指定する必要があります。You must have a cloud-based mobile app with App Service Authentication/Authorization configured, and your client must have the cloud endpoint specified as the alternate login host. 必要な手順の詳細については、クライアント プラットフォームのドキュメントを参照してください。See the documentation for your client platform for the specific steps required.

モバイル バックエンドに Microsoft.Azure.Mobile.Server.Authentication がインストールされていることを確認します。Ensure that your mobile backend has Microsoft.Azure.Mobile.Server.Authentication installed. 次に、MobileAppConfigurationHttpConfiguration に適用された後で、アプリケーションの OWIN Startup クラスに次のコードを追加します。Then, in your application's OWIN startup class, add the following, after MobileAppConfiguration has been applied to your HttpConfiguration:

    app.UseAppServiceAuthentication(new AppServiceAuthenticationOptions()
    {
        SigningKey = ConfigurationManager.AppSettings["authSigningKey"],
        ValidAudiences = new[] { ConfigurationManager.AppSettings["authAudience"] },
        ValidIssuers = new[] { ConfigurationManager.AppSettings["authIssuer"] },
        TokenHandler = config.GetAppServiceTokenHandler()
    });

前の例では、Web.config ファイル内のアプリケーション設定 authAudienceauthIssuer を、HTTPS スキームを使用して、それぞれアプリケーション ルートの URL に構成する必要があります。In the preceding example, you should configure the authAudience and authIssuer application settings within your Web.config file to each be the URL of your application root, using the HTTPS scheme. 同様に、authSigningKey をアプリケーションの署名キーの値に設定する必要があります。Similarly you should set authSigningKey to be the value of your application's signing key. 署名キーを取得するには、次の手順を実行します。To obtain the signing key:

  1. Azure PortalNavigate to your app within the Azure portal
  2. [ツール][Kudu][移動] の順にクリックします。Click Tools, Kudu, Go.
  3. Kudu 管理サイトで、 [環境] をクリックします。In the Kudu Management site, click Environment.
  4. WEBSITE_AUTH_SIGNING_KEY の値を見つけます。Find the value for WEBSITE_AUTH_SIGNING_KEY.

ローカル アプリケーション構成で、authSigningKey パラメーターの署名キーを使用します。モバイル バックエンドは、ローカルで実行されているときに、クライアントがクラウドベースのエンドポイントから取得するトークンを検証できるようになりました。Use the signing key for the authSigningKey parameter in your local application config. Your mobile backend is now equipped to validate tokens when running locally, which the client obtains the token from the cloud-based endpoint.