Office アドインおよび SharePoint アドインのライセンスの XML スキーマ構造Office and SharePoint Add-in license XML schema structure

アドインにライセンス検証チェックを組み込む場合は、このスキーマを使用してテスト ライセンスを作成し、アドインのライセンス検証コードをテストします。If your add-in includes license validation checks, use this schema to create test licenses to test the license validation code in your add-in. 詳細については、「Office アドインと SharePoint アドインにライセンス チェックを追加する」を参照してください。For more information, see Add license checks to Office and SharePoint Add-ins.

AppSource 検証 Web サービスの VerifyEntitlementToken メソッドを使用すると、アドイン ライセンスが有効かどうかを判断できます。Use the VerifyEntitlementToken method of the AppSource verification web service to determine if an add-in license is valid. VerifyEntitlementToken メソッドは、パラメーターとしてアドイン ライセンス トークンを受け取り、ライセンス トークンのプロパティを格納している VerifyEntitlementTokenResponse を返します (ライセンス トークンが有効かどうかを示すプロパティが含まれています)。The VerifyEntitlementToken method takes an add-in license token as a parameter, and returns a VerifyEntitlementTokenResponse that contains the license token properties, including whether or not the license token is valid.

アドインのライセンス チェックをサポートするために、AppSource 検証 Web サービスは暗号化トークンを検証しません。また、テスト属性が true に設定されているライセンス トークンの属性値を検証しません。To support add-in license testing, the AppSource verification web service does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. ただし、このサービスはトークンを解釈して、サービスによって返される VerifyEntitlementTokenResponse オブジェクトのすべてのプロパティを読み取ることができます。However, the service does interpret the token, and all the properties of the VerifyEntitlementTokenResponse object returned by the service can be read.

<r>
  <t 
    aid="{2[A-Z] 8-12[0-9]}" 
    pid="{GUID}" | "string" 
    cid="{16[0-H]}" 
    oid="{GUID}"
    did="{GUID}" 
    ts="Integer" 
    et="Free" |"Trial" | "Paid"
    sl="true | 1" | "false| 0"
    ad="UTC" 
    ed="UTC" 
    sd="UTC" 
    te="UTC" 
    test="true | 1" | "false | 0"
    ss="0" | "1" | "2" | "3" | "4" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>

要素Elements

rr

必須。ルート要素。Required. The root element.

tt

必須。アドイン ライセンスのさまざまなプロパティを表す属性が含まれます。Required. Contains attributes that represent various properties of the add-in license.

属性Attributes

属性Attribute 説明Description
aidaid 必須のテキスト。AppSource によってこのアドインに割り当てられた資産 ID。Required text. The asset ID assigned to this add-in by AppSource.
pidpid 必須のテキスト。アドインの製品 ID を表す GUID。Required text. The GUID that represents the product ID of the add-in.
アドインの製品 ID はアドイン マニフェストで指定します。The product ID of the add-in is specified in the add-in manifest.
cidcid オプションのテキスト。ユーザーが Microsoft アカウントでサインインしている場合に、購入者 ID を表します。これは、アドインの購入者が使用している Microsoft アカウントを暗号化した値です。ユーザーが組織 ID でサインインしている場合は、この値は空になります。Optional text. Represents the purchaser ID when the user is signed in with a Microsoft account. This is an encrypted value of the Microsoft account used by the purchaser of the add-in. If the user is signed in with an organizational identity, this value will be empty.
oidoid オプションのテキスト。ユーザーが組織 ID でサインインしている場合に、購入者 ID を表します。これは、アドインの購入者が使用している組織アカウントを暗号化した値です。ユーザーが Microsoft アカウントでサインインしている場合は、このフィールドは表示されません。Optional text. Represents the purchaser ID when the user is signed in with an organizational identity. This is an encrypted value of the organizational account used by the purchaser of the add-in. If the user is signed in with a Microsoft account, this field will not be present.
diddid Office のコンテンツ アドインと作業ウィンドウ アドインの場合: For content and task pane Office Add-ins:

この属性は Office のコンテンツ アドインと作業ウィンドウ アドインには適用されません。This attribute does not apply to content and task pane Office Add-ins.

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

このアドイン ライセンスが適用される Exchange 展開の展開 ID を表す文字列。この値は Exchange 展開のプライマリ優先ドメインに設定する必要があります。 String that represents the deployment ID of the Exchange deployment to which this add-in license applies. This value should be set to the primary authoritative domain for the Exchange deployment.

SharePoint アドインの場合: For SharePoint Add-ins:

このアドイン ライセンスが適用される SharePoint 展開の展開 ID を表す GUID。GUID that represents the deployment ID of the SharePoint deployment to which this add-in license applies.

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

tsts この購入者によってこのアドインにアクセスすることをライセンスされているユーザーの総数を表す整数。Integer representing the total number of users licensed to access this add-in, by this purchaser.

サイト ライセンスが供与されている場合、この値は 0 になります。For add-ins that are site licensed, this value is 0.

この属性は Office アドインに適用されます。ts = 0 の場合でも、コードに含めます。This attribute applies to Office Add-ins. Include it in your code even if ts=0.

etet 必須のテキスト。アドイン ライセンスのタイプを表す列挙。Required text. Enumeration that represents the type of add-in license.

有効な値は、Free、Paid、および Trial です。Valid values include Free, Paid, and Trial.

adad 必須のテキスト。アドイン ライセンスの取得日を表す UTC 日付/時刻のスタンプ。Required text. UTC time-date stamp that represents the acquisition date for the add-in license.
slsl アドイン ライセンスがサイト ライセンスかどうかを表すブール値。Boolean value that represents whether the add-in license is a site license.

Office のコンテンツ アドインと作業ウィンドウ アドインの場合: For content and task pane Office Add-ins:

この属性は Office のコンテンツ アドインと作業ウィンドウ アドインには適用されません。This attribute does not apply to content and task pane Office Add-ins.

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

この属性は、サイト ライセンス以外のアドイン ライセンスでは省略可能です。サイト ライセンスの Outlook アドインである場合は、この属性に true を指定する必要があります。 This attribute is optional for add-in licenses that are not site licenses. This attribute is required to be equal to true if the Outlook add-in is site licensed.

SharePoint アドインの場合: For SharePoint Add-ins:

この属性は、サイト ライセンス以外のアドイン ライセンスではオプションです。This attribute is optional for add-in licenses that are not site licenses.

eded オプションのテキスト。アドイン ライセンスの有効期限日を表す UTC 日付/時刻のスタンプです。Optional text. UTC time-date stamp that represents the expiration date for the add-in license.

この値を使用して、試用版ライセンスが期限切れになっているかどうかをチェックできます。This value can be used to check if the trial license is expired.

sdsd 必須のテキスト。次のいずれかを表す UTC 日付/時刻のスタンプ。Required text. UTC time-date stamp that represents one of the following:
  • ライセンスを最初に購入した日付と時刻。The initial purchase of the license.
  • Microsoft アカウントを使用して購入者がライセンスの復旧を行った場合、最後に手動でライセンス復旧を実行した日付と時刻。The latest manual license recovery time, if the purchaser has performed such a recovery using their Microsoft account.
tete 必須のテキスト。現在のアドイン ライセンス トークンが期限切れになる日付を表す UTC 日付/時刻のスタンプ。Required text. UTC time-date stamp that represents the date the current add-in license token expires.
テストtest オプションのブール値。アドイン ライセンスがテスト ライセンスかどうかを表します。Optional Boolean value. Represents whether the add-in license is a test license.
ssss オプションの整数。アドイン ライセンスのサブスクリプションの状態を表します。この属性は、サブスクリプションとして販売されていないアドインではオプションです。Optional integer. Represents the subscription status of the add-in license. This attribute is optional for add-ins that are not being sold as subscriptions.

この属性には 0 から 4 までの整数を指定できます。有効な値は以下のとおりです。 This attribute accepts integers from 0 through 4. Valid values include:

整数Integer説明Description
00 NotApplicableNotApplicable

このアドイン ライセンスは、サブスクリプション アドインのものではありません。The add-in license is not for a subscription add-in.

11 ActiveActive

現在、アドイン ライセンス サブスクリプションは、料金が支払われています。The add-in license subscription is currently paid for.

推奨されるユーザー エクスペリエンス: Recommended user experience:

完全なアドインのエクスペリエンス。Full add-in experience.

22 FailedPaymentFailedPayment

アドイン ライセンス サブスクリプションの自動月次請求が失敗しました。The automatic monthly billing for the add-in license subscription has failed.

支払いが失敗する原因はいくつか考えられます。たとえば、請求対象のクレジットカードの有効期限が切れている可能性があります。支払いが失敗した場合は、アドイン ライセンス支払い用の Microsoft アカウントに電子メールが送付されます。ただし、ユーザーが Microsoft アカウントの電子メールを頻繁にはチェックしないことや、SharePoint アドインの場合は、アドイン ライセンスを支払っている人が、アドイン ライセンスを実際に使用している人物ではないことが考えられます。 There are several reasons payment may have failed. For example, the credit card being billed might have expired. When payment fails, emails are sent to the Microsoft account paying for the add-in license. However, the user might not check their Microsoft account email on a frequent basis, or, in the case of SharePoint Add-ins, the person paying for the add-in license may not actually be the person using the add-in license.

推奨されるユーザー エクスペリエンス: Recommended user experience:

アドイン内に課金に関する問題をユーザーに警告する UI を組み込んで、ユーザーが問題を解決できるようにします。Present UI in your add-in alerting the user of the problem with billing, so that they can resolve it.

33 CanceledCanceled

アドイン ライセンスのサブスクリプションがキャンセルされ、ユーザーが料金を支払った最終月の請求期間が経過しました。The add-in license subscription has been canceled, and final monthly billing period the user has paid for has expired.

推奨されるユーザー エクスペリエンス: Recommended user experience:

サブスクリプションがキャンセルされたという旨の情報をユーザーに提示します。アドインに関する情報を、アドインの AppSource の一覧ページへのハイパーリンクと共に表示して、サブスクリプションを更新するように促します。 Present the user with information that their subscription has been cancelled. Provide information about your add-in, along with a hyperlink to your app’s AppSource listing page, so they are encouraged to renew their subscription.

44 DelayedCancelDelayedCancel

アドイン ライセンス サブスクリプションがキャンセルされましたが、サブスクリプションがまだ、支払いの済んだ最終月の請求期間中です。現在の最終月の請求期間が経過すると、サブスクリプションの状態が Canceled に変更されます。 The add-in license subscription has been canceled, but the subscription is still within the current, monthly billing period the user has paid for. Once the current, paid monthly billing period expires, the subscription status changes to Canceled.

推奨されるユーザー エクスペリエンス: Recommended user experience:

完全なアドインのエクスペリエンス。また、ユーザーにサブスクリプションをキャンセルする理由をたずねたり、サブスクリプションの再開を促したりするためにユーザーからのフィードバックを求めるコンテキスト UI を使用することもできます。 Full add-in experience. Additionally, you may want to present contextual UI to ask the user for feedback on why they are canceling their subscription, or to enourage them to re-subscribe.


dd

必須。Required. アドイン ライセンス トークンが有効かどうかを判断するために AppSource 検証サービスによって使用される暗号化トークン。Encryption token used by the AppSource verification service to determine whether the add-in license token is valid. これは、<t> 要素に含まれるリテラル文字列から派生した暗号化署名です。This is an encrypted signature derived from the literal string contained in the <t> element.

AppSource 検証 Web サービスにテスト アドイン ライセンス トークンを発行するとき、このサービスは、<d> 要素内の暗号化署名と <t> 要素に含まれる文字列を比較するチェックを行いません。When you submit a test add-in license token to the AppSource verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element.

解説Remarks

重要

アドインが、そのホスティング環境からアドイン ライセンス トークンを受け取ったときには、それが Office アプリケーションであっても SharePoint であっても、開発者は、検証のために AppSource 検証 Web サービスにトークンを渡す前に、アドインのライセンス トークン文字列を解析などの方法で操作しないようにしてください。When your add-in receives an add-in license token from its hosting environment, be it an Office application or SharePoint, developers are advised not to parse or otherwise manipulate the add-in license token string before passing it to the AppSource 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 AppSource verification web service treats the token as a literal string. AppSource 検証 Web サービスは、<t> 要素の内容を <d> 要素の値 (<t> 要素に格納されているリテラル文字列から導出される暗号化署名) と比較します。The AppSource 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, line breaks, etc., changes the literal value of the <t> element and therefore causes the license verification check to fail.

AppSource 検証 Web サービスにテスト アドイン ライセンス トークンを発行するとき、このサービスは、<d> 要素内の暗号化署名と <t> 要素に含まれる文字列を比較するチェックを行いません。When you submit a test add-in license token to the AppSource verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element. これにより、開発者は、書式に配慮することも、<d> 要素の暗号化署名を生成することもなく、テスト用に独自のテスト アドイン ライセンス トークンを作成できます。This enables developers to create their own test add-in license tokens for testing purposes without worrying about formatting or generating the encryption signature for the <d> element.

例: SharePoint アドインのアドイン ライセンス XMLExample: Add-in license XML for a SharePoint Add-in

次の例は、SharePoint アドインのアドイン ライセンスの XML を示しています。これは、購入者が試用版アドインのライセンスを 30 シート購入したことを表しています。このユーザーは、Microsoft アカウントでサインインしています。The following example shows the add-in license XML for a SharePoint Add-in, representing a trial add-in for which the purchaser has acquired 30 seats. The user is signed in with their Microsoft account.

<r>
  <t 
    aid="WA900006056" 
    pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}" 
    cid="32F3E7FC559F4F49" 
    did="{0672BAE9-B41B-48FE-87F1-7F4D3DD3F3B1}" 
    ts="30" 
    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" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>


次の例は、組織 ID でサインインしているユーザーのアドイン ライセンスを示しています。The following example shows the add-in license for a user who is signed in with their organizational identity. cid 属性が空である点に注目してください。Note that the cid attribute is empty.

<r>
   <t 
     aid="WA104104476" 
     pid="b1485f0b-1807-495b-bf21-c58a82619ac5" 
     cid="" 
     oid="cc2f0903-8765-48a3-9307-92d84829a42f" 
     ts="0" 
     sl="true" 
     et="Free" 
     ad="2015-10-21T13:40:47Z" 
     sd="2015-10-21" 
     te="2016-10-20T13:40:47Z" 
     ss="0" />
     <d>Ymwiorz9SdzbkYrJnYwRzU/Q6zwFyiuXMkJztKCtmQE=</d>
</r>

関連項目See also