Office アドインと SharePoint アドインにライセンス チェックを追加するAdd license checks to Office and SharePoint Add-ins

Office アドインのライセンスを作成してロード テストできます。You can create and load test your Office Add-in licenses. アドインのライセンス チェック コードのテストに利用するために、テスト ライセンスを使用できます。To help you test your add-in's license-checking code, you can use test licenses. Office ランタイムは、このようなテスト トークンを AppSource から取得した有効なトークンであるかのように扱います。ただし、レジストリからロードされるトークンは、有効期限や資格タイプについてテストされません。The Office runtime treats these test tokens as if they were valid tokens acquired from the Office Store, with the exception that tokens loaded through the registry are not tested for expiration or entitlement type. これに該当するテスト ライセンスは、アドイン ライセンスのスキーマ構造に準拠した文字列です。These test licenses are strings that conform to the add-in license schema structure.

テスト トークンを作成するにはTo create a test token:

  • ライセンス スキーマの例をテキスト ファイルにコピーして、そのファイルの拡張子を .tok にして保存します。Copy the example license schema into a text file and save it with a .tok extension.
  • 製品 ID など、該当する属性を変更します。Change the appropriate attributes, such as Product ID.
  • test 属性が存在し、true に設定されていることを確認します。Make sure the test attribute is present and set equal to true.

アドイン ライセンス トークンの検証に使用する AppSource 検証 Web サービスは、暗号化トークンや、test 属性が true に設定されているライセンス トークンの属性値を検証しません。The Office Store verification web service, which you use to verify add-in license tokens, does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. テスト トークンを直接編集し、これらのテスト トークンを使用して、さまざまな属性値に基づいてアドインの動作コードをテストできます。You can edit your test tokens directly and use them to test add-in behavior code based on different attribute values.

Word、Excel、および PowerPoint のアドインの場合:For Word, Excel, and PowerPoint add-ins:

  • テスト トークンを作成します。Create your test tokens.
  • 開発者レジストリを使用して、テスト ライセンス トークンをアップロードします。詳細については、この記事の後で説明する「テスト ライセンスの読み込み」を参照してください。Upload your test license tokens by using the developer registry. For details, see Load a test license later in this article.

Outlook アドインの場合:For Outlook add-ins:

  • 使用するテスト トークンを作成します。Create your test token.
  • URL エンコードされたバージョンのアドイン ライセンス トークンを作成します。Create a URL-encoded version of the add-in license token.
  • アドイン マニフェスト ファイルで、適切な SourceLocation 要素を手動で編集します。URL エンコードされたバージョンのライセンス トークンを et というクエリ パラメーターとしてソースの場所の URL に追加します。In the add-in manifest file, manually edit the appropriate SourceLocation element. Add the URL-encoded version of the license token to the source location URL as a query parameter named et .


    Note

    アドインで getUserIdentityTokenAsync を使用している場合は、マニフェストに SourceLocation 要素を追加すると、トークン内の URL が変更されます。これは、トークンの生成がマニフェストの内容に基づいているためです。ライセンス トークンをテストする場合、変更された URL を検証が受け入れるように、サービスでの検証呼び出しを変更する必要があります。たとえば、マネージ API トークン検証ライブラリを使用する場合は、変更した SourceLocation と一致するように hostUri パラメーターを変更する必要があります。ライセンス チェックをテストした後、必ず Exchange の ID トークン検証呼び出しを元に戻してください。If your add-in uses getUserIdentityTokenAsync, adding to the SourceLocation element in the manifest changes the URL in the token because the token generation is based on what is in the manifest. When you test the license token, you have to modify the validation call on your service so that the validation accepts the modified URL. For example, if you use the managed API token validation library, you need to change the hostUri parameter to match the modified SourceLocation. Remember to change the Exchange identity token validation callback after you test the license check.

Office アドインのコードにラインセンス チェックを実装するImplement license checks in the Office Add-in code

有効なライセンスまたはその他のライセンス情報をアドイン内でチェックするポイントについて検討します。たとえば、アドインが起動するとき、ユーザーが特定のページに移動するとき、またはユーザーが特定の機能にアクセスするときなどです。Think about where in your add-in you want to check for a valid license or other license information; for example, when the add-in launches, or when the user goes to a specific page or accesses certain features.

ライセンスをチェックするには、事前にアドイン ライセンス トークンを取得してキャッシュする必要があります。ユーザーが Office アドインを開くと、Office アプリケーションはアドインのホーム ページを要求します。Office アプリケーションは、ページの URL にクエリ文字列パラメーターとしてライセンス トークンを含めて、ホーム ページを求める HTTP 要求を行います。Before you can check the license, you'll have to acquire and cache the add-in license token. When a user opens an Office Add-in, the Office application requests the add-in home page. The Office application makes the HTTP request for the home page, including the license token as a query string parameter on the page's URL.

たとえば、アドインのホーム ページが次の URL であるとします。For example, suppose your add-in home page has the following URL:

http://myApp/index.html

この URL を呼び出す Office アプリケーションは、次のクエリ文字列を追加してから、この URL を渡します。The Office application calling that URL would add the following query string to it and then pass the URL:

次の URL: http://myApp/index.htm?et= PAByAD4APAB0ACAAYQBpAGQAPQAiAFcAQQAxADAAMgA4ADkAOQA1ADYANgAiACAAcABpAGQAPQAiADMAZAAyADgANwAwADcAYQAtAGYAYwBjAGUALQA0ADUAMQA3AC0AYQBjADYAZQAtAGMAYQAwAGEAZABkADYAMwA3ADMAYQBhACIAIABjAGkAZAA9ACIAMgAzAEEANwBFAEIAOABBADQAQwA0ADcARgA1AEEAMgAiACAAdABzAD0AIgAwACIAIABzAGwAPQAiAHQAcgB1AGUAIgAgAGUAdAA9ACIARgByAGUAZQAiACAAYQBkAD0AIgAyADAAMQAyAC0AMAA1AC0AMgAyAFQAMQA4ADoAMQAyADoAMgAzAFoAIgAgAHMAZAA9ACIAMgAwADEAMgAtADAANQAtADIAMgAiACAAdABlAD0AIgAyADAANgA3AC0AMAAyAC0AMgAzAFQAMQA4ADoAMQA0ADoAMAAwAFoAIgAgAC8APgA8AGQAPgAyADIAWABLAEEAdgA0ADMAQgBtAHMAcwByADAAcgBxADUANQBGAHUAdgBpAFUAVgBSAGkAVgBLAFMASQBEAGcAeAAyAHAAMgA0AFoAZwBzAGwANgBNAD0APAAvAGQAPgA8AC8AcgA%2bAA%3d%3d

クエリ文字列パラメーター et は、アドイン ライセンス トークンの Base-64 および URL エンコード バージョンを指定します。The query string parameter et specifies a base-64 and URL-encoded version of the add-in license token.

Outlook アドインの場合、et クエリ パラメーター文字列は URL エンコードされているのみで、Base-64 エンコードされていませんFor Outlook add-ins, the et query parameter string is only URL-encoded, and not base-64 encoded.

たとえば、Outlook アドインのテスト トークンを含むように変更されたソースの場所は、次のようになります。For example, the source location modified to include a test token for an Outlook add-in would look like this:

https://myApp/index.htm?et=%3Cr%20v%3D%221%22%3E%3Ct%20aid%3D%22WA104108294%22%20pid%3D%22463eafac-c123-45fe-bd21-b1b120b4c12b%22%20cid%3D%223BEC2F1C0124D801%22%20did%3D%22CONTOSO.COM%22%20ts%3D%221%22%20et%3D%22Paid%22%20ad%3D%222013-08-29T21%3A38%3A14Z%22%20sd%3D%222013-09-17%22%20te%3D%222013-12-23T09%3A10%3A42Z%22%20test%3D%221%22%20ss%3D%220%22%20%2F%3E%3Cd%3E7uM9j2%2FYZJeZrrm2TLjXufQlwkAXkq2RqjowBP9fAjo%3D%3C%2Fd%3E%3C%2Fr%3E

Important

セキュリティ上の理由から、Office アドインのライセンスを認証する場合は、アドインのホーム ページに HTTP セキュア (https://) URL を指定してください。For security reasons, if you are licensing your Office Add-in, we strongly recommended that you specify an HTTP Secure ( https://) URL for your add-in home page.

アドイン ライセンス チェックを実行するには、URL からライセンス トークンを抽出してキャッシュするコードをアドインに含めます。これにより、ライセンスを実際に検証する場合に、後でアドインはトークンを検証サービスに渡すことができます。To perform add-in license checks, include code that extracts the license token from the URL and caches it, so that the add-in can pass the token to the verification service later when you want to actually validate the license.

たとえば、次のコードは URL からトークンを抽出し、そのトークンをデコードし、文字列に書式設定します。For example, the following code extracts the token from the URL, decodes the token, and formats it as a string:

// Obtains token URL
string token = Request.Params["et"].ToString(); 

// Applies base64 decoding of the token to get a decoded token.
byte[] decodedBytes = Convert.FromBase64String(token); 
string decodedToken = Encoding.Unicode.GetString(decodedBytes);

Note

トークンが空白を含む場合、デコードでエラーが発生します。トークン内の文字間の空白を必ず処理してください。The decoding will throw an error if the token contains white space. Make sure that you handle white space between characters within the token.

普及と採用が最大になるように、作業ウィンドウ アドインとコンテンツ アドインは匿名アクセスを許可します。To help maximize the reach and adoption, task pane and content add-ins allow anonymous access. 作業ウィンドウ アドインおよびコンテンツ アドインをアクティブ化するために、ユーザーは Office に Microsoft アカウントでサインインする必要はありません。ユーザーが Microsoft アカウントでログインした場合に限り、ライセンス トークンが初期 HTTP 要求の一部として渡されます。Microsoft does not require that a user be signed in to Office with their Microsoft account to activate task pane and content add-ins. The license token is passed as part of the initial HTTP request only if the user is signed in with their Microsoft account.

作業ウィンドウ アドインおよびコンテンツ アドインの場合、コードは HTTP リクエストに et パラメーターがあるかどうかを最初にテストする必要があります。For task pane and content add-ins, your code should first test for the presence of the et parameter in the HTTP request. 存在しない場合は、該当ユーザーを匿名ユーザーとして扱い、適切なユーザー エクスペリエンスを提供する必要があります。If it is not present, you should treat the user as anonymous, and present the appropriate user experience.

詳細については、「Office アドインのアドイン ライセンス トークンと匿名アクセス」を参照してください。For more information, see add-in license tokens and anonymous access for Office Add-ins.

Important

アドイン ライセンス トークン文字列は、検証のために AppSource 検証 Web サービスに渡す前に、解析などの方法で操作しないでください。Do not to parse or otherwise manipulate the add-in license token string before passing it to the Office Store verification web service for verification. アドインのライセンス トークンは、XML フラグメントとして構造化されていますが、AppSource 検証 Web サービスは、検証のためにトークンをリテラル文字列として処理します。While the add-in license token is structured as an XML fragment, for purposes of validation, the Office Store verification web service treats the token as a literal string. AppSource 検証 Web サービスは、<t> 要素の内容を <d> 要素の値 (<t> 要素に格納されているリテラル文字列から導出される暗号化署名) と比較します。The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. ライセンス トークンの書式が変更されると (空白やタブ、改行の追加など)、<t> 要素のリテラル値が変化して、ライセンス検証のチェックの失敗につながります。Any reformatting of the license token, such as adding white space, tabs, or line breaks, changes the literal value of the <t> element and therefore causes the license verification check to fail. また、ライセンス トークン文字列にバイト オーダー マーク (BOM) 追加するサービスやアプリケーションを使用してライセンス トークンを保存しないでください。Also, do not store the license token using a service or application that adds a byte order mark (BOM) to the license token string. 検証サービスに渡すライセンス トークンに、この文字が含まれていると、ライセンス チェックが失敗する原因になります。Including this character in the license token passed to the verification service causes the license check to fail. トークンに BOM を追加するアプリケーションを使用する場合は、この文字を削除してから、検証サービスにライセンス トークンを渡す必要があります。If you do use an application that adds a BOM to the token, you must remove this character before passing the license token to the verification service.

アドインでライセンス チェックを実行する必要がある場合は、検証のためにライセンス トークンを AppSource ライセンス検証 Web サービスに渡します。検証サービスは次の URL にあります。When the add-in needs to perform a license check, pass the license token to the offappstore license verification web service for validation. The verification service is located at the following URL:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc

検証サービスには、ライセンス トークンをパラメーターとし、ライセンスのプロパティを含む VerifyEntitlementTokenResponse オブジェクトを返す、単一のメソッド VerifyEntitlementToken があります。The verification service has a single method VerifyEntitlementToken that takes the license token as a parameter and returns a VerifyEntitlementTokenResponse object that contains the properties of the license. IsValid プロパティは、ライセンス トークンが有効かどうかを指定します。The IsValid property specifies whether the license token is valid. ProductIdEntitlementType などの他のプロパティには、さまざまなライセンス属性に関する情報が含まれます。Other properties, such as ProductId and EntitlementType, contain information about the various license attributes.

AppSource ライセンス検証 Web サービスは、REST 呼び出しを使用したアドイン ライセンス トークンの検証もサポートします。The Office Store license verification web service also supports verifying add-in license tokens by using REST calls. REST を使用してアドイン ライセンスを検証するには、次の構文を使用します。ここで、{token} はアドイン ライセンス トークンであり、JavaScript の encodeURIComponent() 関数や .NET Framework の Uri.EscapeDataString メソッドなどの RFC 2396 に準拠したメソッドでエンコードされます。To validate an add-in license by using REST, use the following syntax, where {token} is the add-in license token, encoded by a method that complies with RFC 2396; for example, the encodeURIComponent() function in JavaScript, or the Uri.EscapeDataString method in the .NET Framework:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc/rest/verify?token={token}

クライアント側のコードから AppSource 検証サービスを呼び出すことはサポートされていません。サーバー側のコードを使用して、AppSource 検証 Web サービスにクエリを実行する必要があります。Calling the offappstore verification service from client-side code is not supported. You must use server-side code to query the offappstore verification web service.

Office アドインでライセンスに基づいて実行する処理のコードを追加するAdd code for the action the Office Add-in takes, based on its license

ライセンスが有効かどうかに基づいて、さらに、ライセンスが有効な場合はその他の重要なライセンス情報に基づいて適切な処理を実行するコードをアドインに追加します。たとえば、ライセンスが有料版の場合はユーザーが特定の機能にアクセスすることを許可し、試用版の場合は許可しないコードなどです。Add code to your add-in that takes the appropriate action, based on whether the license is valid and, if it is valid, based on any other license information that is important to you; for example, code that enables the user to access certain features if the user's license is for the paid version, but not the trial version.

Office アドインでテスト ライセンスの受け入れをブロックするコードを追加するAdd code to block the Office Add-in from accepting test licenses

アドインのテストが完了し、そのアドインを運用環境に移す準備ができたら、アドインのライセンス チェックにコードを追加して、アドインが今後テスト ライセンスを受け入れないようにします。こうすることで、ユーザーがテスト ライセンスを使用してアドインにアクセスすることを禁止します。After you finish testing your add-in and you're ready to move it to production, add code to the license checks in your add-in so that it no longer accepts test licenses. This prevents users from using test licenses to access your add-in.

検証サービスの VerifyEntitlementToken メソッドにアドインのライセンス トークンを渡した後は、そのメソッドから返される VerifyEntitlementTokenResponse オブジェクトを使用して、ライセンスのプロパティにアクセスします。After you pass the add-in license token to the verification service's VerifyEntitlementToken method, use the VerifyEntitlementTokenResponse object returned by that method to access the license properties. テスト用のライセンスについては、IsTest プロパティが true を返し、IsValid プロパティが false を返します。For test licenses, the IsTest property returns true and the IsValid property returns false.

Note

Outlook アドインの場合、テスト ライセンス トークンを表す et パラメーターを、アドイン マニフェスト ファイルのすべての SourceLocation 要素から削除してください。For Outlook add-ins, make sure that you remove the et parameter, which represents the test license token, from all SourceLocation elements in your add-in manifest file.

コード例: Office アドインのライセンスは、アドイン ライセンス トークンを取得して検証することでチェックします。Code example: Check the Office Add-in license by retrieving and validating its add-in license token

次の例は、コンテンツ アドインまたは作業ウィンドウ アドインのライセンス トークンを取得および検証する基本的な論理フローを示しています。The following example shows the basic logic flow of retrieving and validating the license token for a content or task pane add-in:

  1. このコードでは、URL クエリ文字列パラメーター et を取得します。このパラメーターにはエンコードされたライセンス トークンが含まれます。The code retrieves the URL query string parameter, et, which contains the encoded license token.

  2. カスタム関数を使用してライセンス トークンをデコードし、それを Base-64 から AppSource 検証サービスが受け付ける文字列形式に変換します。The code uses a custom function to decode the license token and convert it from base-64 to a string format that the offappstore verification service accepts.

    Note

    Outlook アドインの場合、et クエリ パラメーター文字列は URL エンコードされているのみで、Base-64 エンコードされていませんFor Outlook add-ins, the et query parameter string is only URL-encoded, and not base-64 encoded. このサンプルを Outlook アドインで使用する場合は、Base-64 エンコードからトークンを変換するコードを削除してください。To use this example with an Outlook add-in, remove the code that converts the token from base-64 encoding.

  3. コードは、検証のために文字列形式のトークンを検証サービスに渡します。The code passes the token in string format to the verification service for validation. 検証サービスから検証結果を表す VerifyEntitlementTokenResponse オブジェクトが返されたら、コードはそのオブジェクトのプロパティ (ライセンス トークンの属性を含む) にアクセスできます。After the verification service returns a VerifyEntitlementTokenResponse object that represents the validation results, the code can access the object's properties that contain attributes of the license token.

次の例では、アドイン ユーザーのユーザー ID と、ライセンス トークンがテスト トークンかどうかを出力します。In this example, the code prints out the user ID of the add-in user and whether the license token is a test token.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections.Specialized;
using System.Text;
using EtokenWeb.OmexTokenService;

namespace EtokenWeb{

    public partial class EToken : System.Web.UI.Page{
        public string etoken = "";
        private static VerificationServiceClient service = new VerificationServiceClient();

        protected void Page_Load(object sender, EventArgs e){

            etoken = Request.QueryString["et"];
            if (etoken != null)
            {
                Response.Write("my value:" + etoken + "<br>");
                CallVerificationService(etoken);
            }
            else
                Response.Write("no token provided<br>?");
        }

        private void CallVerificationService(string etoken){
            VerifyEntitlementTokenRequest request = new VerifyEntitlementTokenRequest();
            request.EntitlementToken =  DecodeToken(etoken);
            VerifyEntitlementTokenResponse  omexResponse = service.VerifyEntitlementToken(request);
            Response.Write("Is Test:" + omexResponse.IsTest + "<br>") ;
            Response.Write("User ID: "+ omexResponse.UserId + "<br>") ;
        }

        private static string DecodeToken(string encodedToken){
            byte[] decodedBytes = Convert.FromBase64String(encodedToken);
            return Encoding.Unicode.GetString(decodedBytes);
        }
    }
}

実行時における Office アドインへのアドイン ライセンスの挿入Inject an add-in license into an Office Add-in at runtime

Office アドインと SharePoint アドイン ライセンス モデルを使用すると、アドインに、ライセンスのプロパティに基づいて使用法を検証および適用するコードを組み込むことができます。次のいずれかの場所から、アドインを使用したテスト ライセンスを読み込むことができます。The Office and SharePoint Add-ins licensing model gives you a way to include code in your add-in to verify and enforce how it's used based on the properties of its license. You can load a test license with your add-in from either:

  • アドインの Visual Studio プロジェクト。The Visual Studio project for your add-in.
  • ファイル システム (デベロッパー レジストリ プロバイダーを使用)。The file system by using the Developer Registry provider.

どちらの方法によっても、アドインは AppSource または SharePoint アドイン カタログから起動された場合と同じようにライセンスを取得できます。しかし、テスト ライセンスが Office アドインと SharePoint アドイン ランタイムによって扱われる方法は同じではありません。期限切れまたは資格タイプを調べられることがないので、トークンの更新がトリガーされることも、UI でエラーが起こることもありません。Both methods allow an add-in to get the license the same way it would if it were launched from the Office Store or a SharePoint add-in catalog. However, test licenses aren't treated the same way by the Office and SharePoint Add-ins runtime. They are not tested for expiration or the entitlement type, and therefore won't trigger a token refresh or raise an error in the UI.

Visual Studio プロジェクトからテスト ライセンスを読み込むにはLoad a test license from your Visual Studio project

  1. Visual Studio でコンテンツ アドインまたは作業ウィンドウ アドインのプロジェクトを作成するか、開きます。Create or open a content or task pane add-in project in Visual Studio.

  2. ソリューション エクスプローラーで Office プロジェクト (ソリューションの 2 つのプロジェクトのうち、2 番目の Web プロジェクトではなく、最初の方) を右クリックし、[エクスプローラーでフォルダーを開く] を選択します。In Solution Explorer, right-click the Office project (the first of the two projects in the solution, not the second Web project), and select Open Folder in File Explorer.

  3. ...bin\Debug\OfficeAppManifests に移動します (プロジェクトがリリース ビルド用に設定されている場合は、「デバッグ」を「リリース」に置き換えてください)。Go to ...bin\Debug\OfficeAppManifests (substitute "Debug" with "Release" if your project is configured for Release builds). このフォルダーは、プロジェクトを初めてビルドまたはデバッグした後に自動的に作成されます。This folder is created automatically after the first time you build or debug your project.

  4. トークン ファイルをフォルダーに追加します。Add a token file to the folder. トークン ファイル名は、マニフェスト ファイル名と同じで、.tok ファイル拡張子を持たなければなりません。The token file name must be the same as the manifest file name and have a .tok file extension. 次のコードはトークン ファイルの一例を示します。The following code shows an example of a token file. トークン ファイルの <t> 要素に設定できる属性値の詳細については、「Office および SharePoint アドイン ライセンスの XML スキーマ構造」を参照してください。Refer to the Office and SharePoint Add-in license XML schema structure for details about the attribute values you can set in the <t> element of the token file.

    この例では、ユーザーが Microsoft アカウントでサインインしています。In this example, the user is signed in with a Microsoft account. cid 値は Microsoft アカウントのユーザー用に設定されています。The cid value is set for Microsoft account users.

    <r>
      <t 
        aid="WA900006056"
        pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
        cid="32F3E7FC559F4F49"
        et="Trial"
        ad="2012-01-12T21:58:13Z"
        ed="2012-06-30T21:58:13Z"
        sd="2012-01-12T00:00:00Z" 
        te="2012-06-30T02:49:34Z"
        ts="0"
        test="true"/>
      <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
    </r>
    

    次の例に示されているように、ユーザーが組織 ID を使用してサインインする場合は、oid 属性値が設定され、cid 値は空白になります。If the user is signed in with their organizational identity, theoid attribute value is set and the cid value is blank, as shown in the following example.

    <r>
      <t 
        aid="WA900006056"
        pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
        cid=""
        oid="4e8c79ae-327e-495b-a797-fdee87648816"
        et="Trial"
        ad="2012-01-12T21:58:13Z"
        ed="2012-06-30T21:58:13Z"
        sd="2012-01-12T00:00:00Z"
        te="2012-06-30T02:49:34Z"
        ts="0"
        test="true"/>
      <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
    </r>
    
  5. [デバッグ] > [デバッグの開始] の順に選択するか、F5 を選択します。Select Debug > Start debugging, or select F5.

    Note

    発行時に、展開エラーがあり、<d> タグで指定されたライセンス トークンが読み込まれないというメッセージが Visual Studio から表示されます。At the time of publication, Visual Studio displays a message that there were deployment errors, and the license token specified in the <d> tag won't be loaded. ただし、その他のライセンスの値は読み込まれ、アドインのライセンス チェック コードで使用できるようになります。However, the other values in the license are loaded and are available to your add-in license check code.

  6. テスト ライセンスが読み込まれたことを目視で確認するには、アドイン ウィンドウの右上隅にあるポップアップ メニューを選択し、[セキュリティ情報] を選びます。To visually confirm that the test license is loaded, select the pop-out menu in the upper-right corner of the add-in pane, and then select Security Info.

ファイル システムからテスト ライセンスを読み込むLoad a test license from the file system

  1. UNC パスでアクセス可能なフォルダーを作成します (c:\folder または \\server\share)。Create a folder that is accessible via a UNC path (c:\folder or \\server\share).
  2. そのフォルダーに、アドイン用のマニフェスト ファイルを追加します (ファイル名には .xml の拡張子が必要です)。Add the manifest file for your add-in to the folder (the file name must have an .xml extension).

    <?xml version="1.0" encoding="utf-8"?>
    <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ContentApp">
    <Id>9C4675F6-45A0-47EE-B9A4-D834F45467672</Id>
    <Version>15.0</Version>
    <ProviderName>Microsoft</ProviderName>
    <DefaultLocale>en-us</DefaultLocale>
    <DisplayName DefaultValue="GetToken">
    </DisplayName>
    <Description DefaultValue="Get Token">
    </Description>
    <Hosts>
        <Host Name="Workbook"/>
    </Hosts>
    <DefaultSettings>
        <SourceLocation DefaultValue="http://MyServer/GetToken.htm">
        </SourceLocation>
        <RequestedWidth>400</RequestedWidth>
        <RequestedHeight>400</RequestedHeight>
    </DefaultSettings>
    <Permissions>ReadWriteDocument</Permissions>
    <AllowSnapshot>true</AllowSnapshot>
    </OfficeApp>
    
  3. トークン ファイルをフォルダーに追加します。Add the token file to the folder. トークン ファイル名は、マニフェスト ファイル名と同じで、.tok ファイル拡張子を持たなければなりません。The token file name must be the same as the manifest file name and must have a .tok file extension. 次のコードはトークン ファイルの一例を示します。The following code shows an example token file. トークン ファイルの <t> 要素に設定できる属性値の詳細については、「Office および SharePoint アドイン ライセンスの XML スキーマ構造」を参照してください。Refer to the Office and SharePoint Add-in license XML schema structure for details about the attribute values you can set in the <t> element of the token file.

    <r>
      <t 
        aid="WA900006056"
        pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
        cid="32F3E7FC559F4F49"
        et="Trial"
        ad="2012-01-12T21:58:13Z"
        ed="2012-06-30T21:58:13Z"
        sd="2012-01-12T00:00:00Z"
        te="2012-06-30T02:49:34Z"
        ts="0"
        test="true"/>
      <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
    </r>
    
  4. 次のパスのいずれかのマニフェストをポイントするエントリをレジストリに作成します。Create an entry in the registry that points to the manifest under one of the following paths:

    • HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Developer (Office 2013)HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Developer (Office 2013)
    • HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Wef\Developer (Office 2016)HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Wef\Developer (Office 2016)

    次の例に示すように、.reg ファイルを使用できます。You can use a .reg file, as shown in the following example. (この例では、名前フィールド、"entry1"、および .xml ファイル名は任意です。)(Note that the name field, "entry1" and the .xml file name in this example are arbitrary.)

    Windows Registry Editor Version 5.00
    
    [HKEY_CURRENT_USER\Software\Microsoft\Office\16.0\Wef\Developer]
    "entry1"="C:\\folder\\AppFile.xml"
    

SharePoint アドインにライセンス チェック機能を追加するAdd license checks to your SharePoint Add-in

テスト ライセンスを作成し、SharePoint 展開にインポートできます。You can create test licenses and import them into your SharePoint deployment. アドイン ライセンス チェック コードのテストを支援するため、SharePoint では展開ごとに最大 10 のテスト ライセンスをアップロードできます。To assist in testing the add-in license checking code, SharePoint enables you to upload up to ten test licenses per deployment. これらのテスト ライセンスは、Office および SharePoint アドイン ライセンスの XML スキーマ構造に準拠する XML フラグメントです。These test licenses are XML fragments that conform to the Office and SharePoint Add-in license XML schema structure.

テスト ライセンスをインポートするには、ImportAppLicense メソッドを使用します。To import test licenses, use the ImportAppLicense method. このメソッドを呼び出すには、呼び出し元は次のいずれかである必要があります。To call this method, the caller must be one of the following:

  • 呼び出すサイト コレクションの管理者。An administrator of the site collection being called.
  • ライセンスのインポート先テナンシーの管理者 (ライセンスのインポート先 SharePoint 展開がテナンシーの場合)。An administrator of the tenancy into which the license is imported, if the SharePoint deployment into which the license is imported is a tenancy.
  • ファーム管理者。A farm administrator.

テスト ライセンスをインポートすると、SharePoint UI に表示されます。インポートしたテスト ライセンスは、管理、割り当て、削除を行えます。After you import the test licenses, they appear in the SharePoint UI, and you can manage, assign, and delete them.

テスト ライセンスの場合は、アドインのライセンス XML に展開 ID を指定する必要はありません。For test licenses, you don't have to specify the deployment ID in the add-in license XML. ImportAppLicense メソッドにより、適切な展開 ID がライセンス トークン XML に指定されます。The ImportAppLicense method supplies the correct deployment ID to the license token XML.

コード例: SharePoint にテスト ライセンス トークンをインポートするCode example: Import a test license token into SharePoint

次の例では、テスト アドイン ライセンス トークンを取得して、指定された SharePoint インストールにインポートします。The following example takes a test add-in license token and imports it into the specified SharePoint installation.

// For this example to work, you must add a reference in your project to Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll.

string rawXMLEntitlementToken = <token that you want to import>;
string webUrl = "http://localhost" // This localhost URL should be replaced with the URL of any site within the tenancy into which 
// You want to import the license.

using (ClientContext ctx = new ClientContext(webUrl))
{
    Microsoft.SharePoint.Client.Utilities.Utility.ImportAppLicense(
        context: ctx,
        licenseTokenToImport: rawXMLEntitlementToken,
        contentMarket: "en-US", // Replace this with whatever content market you want
        billingMarket8; "US", // Replace this with whatever billing market you want
        appName: "add-in Name", // Replace this with the name of the app
        iconUrl: "http://www.office.com", // Replace this with the URL of the icon of the add-in (as it appears on AppSource),
// Or you can simply leave the URL blank.
        providerName: "Provider Name"); // Replace this with the name of the provider of the app

    ctx.ExecuteQuery();
}

SharePoint アドイン コードへのアドイン ライセンス チェック機能の実装Implement add-in license checks in your SharePoint Add-in code

有効なライセンスまたはその他のライセンス情報をアドイン内でチェックするポイントを識別します。たとえば、アドインが起動するとき、ユーザーが特定のページに移動するとき、またはユーザーが特定の機能にアクセスするときなどです。Identify where in your add-in you want to check for a valid license or other license information; for example, when the add-in launches, or when the user goes to a specific page or accesses certain features. ライセンス トークンについて SharePoint 展開にクエリするコードをこれらのポイントに追加し、そのトークンを検証のために AppSource 検証 Web サービスに渡します。Add code at these points that queries your SharePoint deployment for the license token, and then passes that token to the Office Store verification web service for validation.

SharePoint からライセンス トークンを取得するには、GetAppLicenseInformation メソッドを使用します。To retrieve the license token from SharePoint, use the GetAppLicenseInformation method. このメソッドは、マニフェスト ファイル内のアドイン製品 ID に基づいて、対象ユーザーに当てはまる指定されたアドインのすべてのライセンスを返します。This method returns all licenses for the specified add-in that apply to the user, based on the add-in product ID in the manifest file.

さまざまな Microsoft アカウントを使用して同じアドインに対して複数のライセンスが購入されている場合、ライセンスは次の優先順序で返されます。If multiple licenses are purchased for the same add-in by using different Microsoft accounts, the licenses are returned in the following order of priority:

  • 有料版Paid
  • 無料版Free
  • 試用版 (有効期限が切れていないもの)Unexpired Trial
  • 試用版 (有効期限が切れたもの)Expired Trial

GetAppLicenseInformation メソッドは、期限切れまたは保持されたトークンを持ったライセンスを返しません。The GetAppLicenseInformation method does not return licenses with expired or preserved tokens. 保持されたトークンは、SharePoint が自動的に更新できないライセンス トークンです。Preserved tokens are the license tokens that cannot be renewed automatically by SharePoint. 有効性を維持するには、購入者が AppSource にサインインし、保持されたトークンを手動で更新する必要があります。To remain valid, preserved tokens must be renewed manually by having the purchaser sign in to the Office Store.

コード例: アドイン ライセンス トークンを取得するCode example: Retrieve add-in license tokens

次の例では、現在のユーザーのアドイン ライセンスすべてを、反復処理できるコレクションとして取得します。The following example retrieves all the add-in licenses for the current user as a collection that can be iterated through.

// For this example to work, you must add a reference in your project to Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll.
// For this API to work, the SharePoint deployment you are calling must be able to communicate with ACS to validate OAuth tokens.

string webUrl = "http://localhost" // This localhost URL should be replaced with the URL of the add-in web or host web of the app.
    // If you are redirected from the add-in web to the third-party side executing this code
    // in the code-behind, you can get the add-in web URL with 
    // HttpContext.Current.Request.QueryString["AppWebUrl"].

productId = new Guid(<product ID of the app>);
using(ClientContext ctx = new ClientContext(webUrl))
{
    ClientResult<AppLicenseCollection> licensecollection = Microsoft.SharePoint.Client.Utilities.Utility.GetAppLicenseInformation(ctx, productId);
    ctx.ExecuteQuery();
}

この例の終わりまでに、AppLicense オブジェクトのコレクションとして、licensecollection に現在のユーザーのすべてのアドイン ライセンスが含まれます。By the end of this example, licensecollection includes all the add-in licenses for the current user as a collection of AppLicense objects. RawXMLLicenseToken プロパティを使用してライセンス トークン XML にアクセスできます。You can use the RawXMLLicenseToken property to access the license token XML. たとえば、コレクション内の最初のアドイン ライセンス トークンのライセンス トークンにアクセスするには、licensecollection.Value[0].RawXMLLicenseToken を使用します。So, for example, to access the license token for the first add-in license token in the collection, you use licensecollection.Value[0].RawXMLLicenseToken.

Important

アドイン ライセンス トークン文字列は、検証のために AppSource ライセンス検証 Web サービスに渡す前に、解析などの方法で操作しないでください。Do not to parse or otherwise manipulate the add-in license token string before passing it to the Office Store license verification web service for verification. アドイン ライセンス トークンは XML フラグメントとして構造化されていますが、AppSource 検証 Web サービスは、検証のためにトークンをリテラル文字列として処理します。Although the add-in license token is structured as an XML fragment, for purposes of validation, the Office Store verification web service treats the token as a literal string. AppSource 検証 Web サービスは、<t> 要素の内容を <d> 要素の値 (<t> 要素に格納されているリテラル文字列から導出される暗号化署名) と比較します。The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. ライセンス トークンの書式が変更されると (空白やタブ、改行の追加など)、<t> 要素のリテラル値が変化して、ライセンス検証の失敗につながります。Any reformatting of the license token, such as adding white space, tabs, or line breaks, changes the literal value of the <t> element and causes the license verification check to fail.

アドイン ライセンス トークンを検証するValidate the add-in license token

適切なアドイン ライセンス トークンを取得したら、そのトークンを検証のために AppSource 検証 Web サービスに渡します。検証サービスは次の URL にあります。After you retrieve the appropriate add-in license token, pass that token to the offappstore verification web service for validation. The verification service is located at the following URL:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc

検証サービスには、アドイン ライセンス トークンをパラメーターとし、ライセンスのプロパティを含む VerifyEntitlementTokenResponse オブジェクトを返す、単一のメソッド VerifyEntitlementToken があります。The verification service has a single method, VerifyEntitlementToken, which takes the add-in license token as a parameter and returns a VerifyEntitlementTokenResponse object that contains the properties of the license. IsValid プロパティは、ライセンス トークンが有効かどうかを指定します。ProductIdEntitlementType などの他のプロパティには、さまざまなライセンス属性に関する情報が含まれます。The IsValid property specifies whether the license token is valid, and other properties, such as ProductId and EntitlementType, contain information about the various license attributes.

AppSource ライセンス検証 Web サービスは、REST 呼び出しを使用したアドイン ライセンス トークンの検証もサポートします。REST を使用してアドイン ライセンスを検証するには、次の構文を使用します。The offappstore license verification web service also supports verifying add-in license tokens by using REST calls. To verify an add-in license by using REST, use the following syntax:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc/rest/verify?token={token}

ここで、{token} はアドイン ライセンス トークンであり、JavaScript の encodeURIComponent() 関数や .NET Framework の Uri.EscapeDataString メソッドなどの RFC 2396 に準拠したメソッドでエンコードされます。Where {token} is the add-in license token, encoded by a method that complies with RFC 2396; for example, the encodeURIComponent() function in JavaScript, or the Uri.EscapeDataString method in the .NET Framework. AppSource 検証サービスは、クライアント側のコードからの呼び出しには対応していません。The offappstore verification service does not support being called from client-side code.

Note

SharePoint でアドイン ページをホストしている場合は、SharePoint Web プロキシを使用して、AppSource 検証サービスへの JavaScript 呼び出しを実行できます。If you're hosting your add-in pages on SharePoint, you can use the SharePoint web proxy to make JavaScript calls to the Office Store verification service. ただし、セキュリティ上の理由から、AppSource 検証 Web サービスを照会する場合は、サーバー側のコードのみを使用してください。However, for security reasons we strongly recommend that you use only server-side code to query the Office Store verification web service.

Warning

また、ライセンス トークン文字列にバイト オーダー マーク (BOM) 追加するサービスやアプリケーションを使用してライセンス トークンを保存しないでください。Do not store the license token by using a service or application that adds a byte order mark (BOM) to the license token string. 検証サービスに渡すライセンス トークンに、この文字が含まれていると、ライセンス チェックが失敗する原因になります。Including this character in the license token passed to the verification service causes the license check to fail. トークンに BOM を追加するアプリケーションを使用する場合は、この文字を削除してから、検証サービスにライセンス トークンを渡す必要があります。If you do use an application that adds a BOM to the token, you must remove this character before passing the license token to the verification service.

SharePoint アドイン ライセンスに基づいて処理するTake action based on the SharePoint Add-in license

ライセンスが有効かどうかに基づいて、さらに、ライセンスが有効な場合はその他の重要なライセンス情報に基づいて、適切な処理を実行するコードをアドインに追加します。たとえば、ライセンスが有料版の場合はユーザーが特定の機能にアクセスすることを許可し、試用版アドインの場合は許可しないコードを追加します。Add code to your add-in that takes the appropriate actions, based on whether the license is valid and, if it is valid, any other license information that is important to you; for example, add code that enables the user to access certain features if their license is for the paid version, but not if their license is for the trial version of the add-in.

テスト ライセンスをブロックするコードを追加するAdd code to block test licenses

最後に、アドインのテストが完了し、運用環境に移す準備ができたら、ライセンス チェックにコードを追加して、アドインが今後テスト ライセンスを受け入れないようにする必要があります。こうすることで、ユーザーがテスト ライセンスを使用して SharePoint 展開のアドインにアクセスすることを防止します。Finally, after you finish testing your add-in and are ready to move it to production, you need to add code to the license checks so that the add-in no longer accepts test licenses. This prevents users from using test licenses to access your add-in on their SharePoint deployment.

検証サービスの VerifyEntitlementToken メソッドにライセンス トークンを渡した後、そのメソッドから返される VerifyEntitlementTokenResponse オブジェクトを使用して、ライセンスのプロパティにアクセスできます。After you pass the license token to the verification service's VerifyEntitlementToken method, you can use the VerifyEntitlementTokenResponse object returned by that method to access the license properties. テスト用のライセンスについては、IsTest プロパティが true を返し、IsValid プロパティが false を返します。For test licenses, the IsTest property returns true and the IsValid property returns false.

コード例: SharePoint アドインのライセンス チェックCode example: SharePoint Add-ins licensing checking

次の例では、SharePoint 展開からアドインのライセンス トークンを取得し、そのトークンを検証のために AppSource 検証サービスに渡します。この例では、検証が失敗した場合のさまざまなエラーに対応します。また、検証が成功した場合は、さまざまなライセンス プロパティから文字列を構築します。最後に、ライセンスの種類 (無料版、有料版、または試用版) に基づいてアドイン機能のレベルを指定します。The following example retrieves an add-in's license token from the SharePoint deployment and passes the token to the Office Store verification service for validation. The example catches a variety of possible errors if the verification fails. If the verification succeeds, it builds a string from the various license properties. Finally, the code provides logic for specifying the level of functionality based on the license type: Free, Paid, or Trial.

この例では、Microsoft.SharePoint.Client.Utilities への参照と、AppSource 検証サービスへの Web サービス参照が必要です。This example requires a reference to Microsoft.SharePoint.Client.Utilities, and a web service reference to the Office Store verification service.

//Get the license token XML from SharePoint.
this.rawToken = GetLicenseTokenFromSP(this.productId, this.clientcontext);

//Call the AppSource verification service.
VerifyLicenseToken(this.rawToken);

private string GetLicenseTokenFromSP(Guid productId, ClientContext clientContext)
{
    //Get the license from SharePoint.
    ClientResult<AppLicenseCollection> licenseCollection = Utility.GetAppLicenseInformation(clientContext, productId);
    clientContext.Load(clientContext.Web);
    clientContext.ExecuteQuery();

    foreach (AppLicense license in licenseCollection.Value)
    {
        //Just get the first license token for now.
        rawLicenseToken = license.RawXMLLicenseToken;
        break;
    }
    return (rawLicenseToken);
}

private void VerifyLicenseToken(string rawLicenseToken)
{    
    if (string.IsNullOrEmpty(rawLicenseToken))
    {
        licVerifyEndPoint.Text = "There is no valid license for this user in SharePoint (OR) license cannot be obtained due to some error - check ULS.";
        return;
    }

    VerificationServiceClient service = null;
    VerifyEntitlementTokenResponse result = null;
    VerifyEntitlementTokenRequest request = new VerifyEntitlementTokenRequest();
    request.RawToken = rawLicenseToken;
    lblSPLicenseText.Text = System.Web.HttpUtility.HtmlEncode(request.RawToken);   

    try
    {
        service = new VerificationServiceClient();
        result = service.VerifyEntitlementToken(request);
    }
    catch (EndpointNotFoundException)
    {
        licVerifyEndPoint.Text = "Cannot access verification service endpoint";
    }
    catch (FaultException<ServiceUnavailableFault>)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service is unavailable.";
    }
    catch (FaultException<ServiceInternalErrorFault> internalFault)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service failed. Details: " + internalFault.Detail.Message;
    }
    catch (Exception exception)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service failed. Details: " + exception;
    }

    if (result != null &amp;&amp; result.AssetId !=null)
    {
        string licenseDetails = string.Format("Asset Id: {0}; Product Id: {1}; License Type: {2}; Is Valid: {3}; License Acquisition Date: {4}; License Expiry Date: {5}; IsExpired: {6}; IsTest: {7}; IsSiteLicense: {8}; Seats: {9}; TokenExpiryDate: {10}",
                result.AssetId, result.ProductId, result.EntitlementType, result.IsValid, result.EntitlementAcquisitionDate, result.EntitlementExpiryDate, result.IsExpired, result.IsTest, result.IsSiteLicense, result.Seats, result.TokenExpiryDate);

        if (result.EntitlementType.ToUpper() == "FREE")
        {
          //Allow basic functionality
        }
        else if (result.EntitlementType.ToUpper() == "PAID")
        {
          //Allow all functionality
        }
        else //trial
        {
          //Allow limited functionality
        }
    }
            else
    {
        licVerifyEndPoint.Text = "Verification service didn't return any results";
    }
}

関連項目See also