カスタム関数の JSON メタデータを手動で作成する

[アーティクル]
08/06/2024

カスタム関数の概要に関する記事で説明されているように、カスタム関数プロジェクトには、JSON メタデータファイルとスクリプト (JavaScript または TypeScript) ファイルの両方を含めて関数を登録し、使用できるようにする必要があります。カスタム関数は、ユーザーが初めてアドインを実行したときに登録され、その後、すべてのブックで同じユーザーが使用できるようになります。

重要

Excel カスタム関数は、次のプラットフォームで使用できます。

Office on the web
Windows での Office
- Microsoft 365 サブスクリプション
- retail 永久 Office 2016 以降
- ボリュームライセンスの永続的な Office 2021 以降
Office on Mac

Excel カスタム関数は現在、次ではサポートされていません。

Office on iPad
Windows での Office 2019 以前のボリュームライセンスの永続的バージョン

独自の JSON ファイルを作成する代わりに、可能な場合は JSON 自動生成を使用することをお勧めします。自動生成はユーザーエラーが発生しにくく、 yo office スキャフォールディングされたファイルには既にこれが含まれています。 JSDoc タグと JSON 自動生成プロセスの詳細については、「カスタム関数の JSON メタデータの自動生成」を参照してください。

ただし、カスタム関数プロジェクトはゼロから作成できます。このプロセスでは、次の作業を行う必要があります。

JSON ファイルを書き込みます。
マニフェストファイルが JSON ファイルに接続されていることを確認します。
関数を登録するために、スクリプトファイルに関数の id と name プロパティを関連付けます。

次の図は、スキャフォールディングファイルの使用と JSON のゼロからの書き込みの違い yo office 説明しています。

Office アドインに Yeoman ジェネレーターを使用することと、独自の JSON を記述することの違いの画像。

注:

Office アドイン用の Yeoman ジェネレーターを使用しない場合は、アドイン専用マニフェストファイルの <Resources> セクションを使用して、マニフェストを作成した JSON ファイルに接続してください。

メタデータの作成とマニフェストへの接続

プロジェクトに JSON ファイルを作成し、関数のパラメーターなど、その中の関数に関するすべての詳細を指定します。関数プロパティの完全な一覧については、次のメタデータの例とメタデータリファレンスを参照してください。

アドインのみのマニフェストファイルが、次の例のように、<Resources> セクションの JSON ファイルを参照していることを確認します。

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

JSON メタデータの例

次の例では、カスタム関数を定義するアドインの JSON メタデータファイルの内容を示します。この例の後に続くセクションでは、JSON の例に含まれる個々のプロパティの詳細について説明します。

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

注:

完全なサンプル JSON ファイルは、 OfficeDev/Excel-Custom-Functions GitHub リポジトリのコミット履歴で入手できます。プロジェクトが JSON を自動的に生成するように調整されているため、手書き JSON の完全なサンプルは、以前のバージョンのプロジェクトでのみ使用できます。

メタデータリファレンス

allowCustomDataForDataTypeAny

allowCustomDataForDataTypeAny プロパティはブール型です。この値を true に設定すると、カスタム関数はデータ型をパラメーターとして受け入れ、値を返すことができます。詳細については、「カスタム関数とデータ型」を参照してください。

注:

他のほとんどの JSON メタデータプロパティとは異なり、 allowCustomDataForDataTypeAny は最上位のプロパティであり、サブプロパティが含まれています。このプロパティの書式を設定する方法の例については、前の JSON メタデータコードサンプルを参照してください。

allowErrorForDataTypeAny

allowErrorForDataTypeAny プロパティはブール型です。値を true に設定すると、カスタム関数でエラーを入力値として処理できます。型 any または any[][] を持つすべてのパラメーターは、 allowErrorForDataTypeAny が true に設定されている場合、入力値としてエラーを受け取ることができます。既定の allowErrorForDataTypeAny 値は falseです。

注:

他の JSON メタデータプロパティとは異なり、 allowErrorForDataTypeAny は最上位のプロパティであり、サブプロパティが含まれています。このプロパティの書式を設定する方法の例については、前の JSON メタデータコードサンプルを参照してください。

functions

functions プロパティは、カスタム関数オブジェクトの配列です。次の表に、各オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`description`	文字列	いいえ	Excel でエンドユーザーに表示される関数の説明です。たとえば、「華氏の値を摂氏に変換する」です。
`helpUrl`	文字列	いいえ	関数に関する情報を提供する URL です (作業ウィンドウに表示されます)。たとえば、`http://contoso.com/help/convertcelsiustofahrenheit.html` です。
`id`	string	はい	関数の一意の ID です。この ID には、英数字とピリオドしか使用できません。また、設定後に変更してはいけません。
`name`	文字列	はい	Excel でエンドユーザーに表示される関数の名前です。 Excel では、この関数名の前に、アドインのみのマニフェストファイルで指定されているカスタム関数名前空間が付きます。
`options`	object	いいえ	Excel で関数を実行する方法とタイミングの一部をユーザーがカスタマイズできます。詳細については、options に関する説明を参照してください。
`parameters`	配列	はい	関数の入力パラメーターを定義する配列です。詳細については、「パラメーター」を参照してください。
`result`	object	はい	関数が返す情報の種類を定義するオブジェクトです。詳細については、result に関する説明を参照してください。

options

options オブジェクトでは、Excel で関数を実行する方法とタイミングの一部をユーザーがカスタマイズできます。次の表に、options オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`cancelable`	ブール	いいえ既定値は、`false` です。	`true` の場合、手動での再計算のトリガーや、関数によって参照されているセルの編集など、関数をキャンセルする効果のある操作をユーザーが実行すると、Excel によって `CancelableInvocation` ハンドラーが呼び出されます。取り消し可能な関数は通常、1 つの結果を返す非同期関数にのみ使用され、データに対する要求の取り消しを処理する必要があります。関数では、 `stream` プロパティと `cancelable` プロパティの両方を使用することはできません。
`requiresAddress`	ブール値	いいえ既定値は、`false` です。	`true`場合、カスタム関数は、それを呼び出したセルのアドレスにアクセスできます。呼び出しパラメーターの `address` プロパティには、カスタム関数を呼び出したセルのアドレスが含まれています。関数では、 `stream` プロパティと `requiresAddress` プロパティの両方を使用することはできません。
`requiresParameterAddresses`	ブール値	いいえ既定値は、`false` です。	`true`場合、カスタム関数は関数の入力パラメーターのアドレスにアクセスできます。このプロパティは、結果オブジェクトの `dimensionality` プロパティと組み合わせて使用し、`dimensionality`を `matrix` に設定する必要があります。詳細については、「パラメーターのアドレスを検出する」を参照してください。
`stream`	ブール値	いいえ既定値は、`false` です。	`true` の場合、1 回のみ呼び出されたときにも、関数はセルに繰り返し出力できます。このオプションは、株価などの急速に変化するデータソースに便利です。この関数には、`return` ステートメントは含めないようにする必要があります。代わりに、結果の値は、 `StreamingInvocation.setResult` コールバック関数の引数として渡されます。詳細については、「ストリーミング関数を作成する」を参照してください。
`volatile`	ブール値	いいえ既定値は、`false` です。	`true`場合、関数は、数式の依存値が変更された場合にのみではなく、Excel が再計算されるたびに再計算されます。関数では、 `stream` プロパティと `volatile` プロパティの両方を使用することはできません。 `stream`プロパティと`volatile`プロパティの両方が`true`に設定されている場合、volatile プロパティは無視されます。

parameters

parameters プロパティは、パラメーターオブジェクトの配列です。次の表に、各オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`description`	文字列	いいえ	パラメーターの説明です。これは Excel の IntelliSense に表示されます。
`dimensionality`	文字列	いいえ	`scalar` (配列以外の値) または`matrix` (2 次元配列) である必要があります。
`name`	string	はい	パラメーターの名前です。この名前は、Excel の IntelliSense に表示されます。
`type`	文字列	いいえ	パラメーターのデータ型です。 `boolean`、`number`、`string`、または`any`を使用できます。これにより、前の 3 種類のいずれかを使用できます。このプロパティが指定されていない場合、データ型は既定で `any`されます。
`optional`	ブール値	いいえ	`true` の場合、パラメーターは省略可能です。
`repeating`	ブール値	いいえ	`true`場合、パラメーターは指定した配列から設定されます。関数のすべての繰り返しパラメーターは、定義上省略可能なパラメーターと見なされることに注意してください。

result

result オブジェクトは、この関数が返す情報の種類を定義します。次の表に、result オブジェクトのプロパティを示します。

プロパティ	データ型	必須	説明
`dimensionality`	文字列	いいえ	`scalar` (配列以外の値) または`matrix` (2 次元配列) である必要があります。
`type`	文字列	いいえ	結果のデータ型。 `boolean`、`number`、`string`、または`any`を指定できます (これは、前の 3 種類のいずれかを使用できます)。このプロパティが指定されていない場合、データ型は既定で `any`されます。

関数名を JSON メタデータに関連付ける

関数が正常に機能するには、関数の id プロパティを JavaScript 実装に関連付ける必要があります。関連付けがあることを確認します。それ以外の場合、関数は登録されないため、Excel では使用できません。次のコードサンプルは、 CustomFunctions.associate() 関数を使用して関連付けを行う方法を示しています。このサンプルではカスタム関数 add を定義し、それを id プロパティ値が ADD の、JSON メタデータファイル内のオブジェクトに関連付けます。

/**
 * Add two numbers
 * @customfunction
 * @param {number} first First number
 * @param {number} second Second number
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

次の JSON は、前のカスタム関数 JavaScript コードに関連付けられている JSON メタデータを示しています。

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

JavaScript ファイルでカスタム関数を作成し、JSON のメタデータファイルに対応する情報を指定するときは、次のベストプラクティスに留意してください。

JSON のメタデータファイルにそれぞれの id プロパティには、英数字とピリオドのみが含まれています。
JSON のメタデータファイルで、各 id プロパティの値が、ファイルのスコープ内で一意であることを確認します。すなわち、メタデータファイル内の 2 つの関数オブジェクトは同じ id 値であってはいけません。
対応する JavaScript 関数の名前に関連付けられた後では、JSON のメタデータファイル内の id プロパティの値を変更しないでください。 JSON のメタデータファイル内の name プロパティを更新することによって Excel でエンドユーザーに表示される関数の名前を変更することができます。しかし、確立された後は、 id プロパティの値を決して変更しないでください。
JavaScript ファイルで、各関数の後に CustomFunctions.associate を使用してカスタム関数の関連付けを指定します。

次の例は、前の JavaScript コードサンプルで定義されている関数に対応する JSON メタデータを示しています。 idプロパティとnameプロパティの値は大文字です。これは、カスタム関数を記述する際のベストプラクティスです。この JSON を追加する必要があるのは、自動生成を使用せず、独自の JSON ファイルを手動で準備している場合のみです。自動生成の詳細については、「カスタム関数の JSON メタデータの自動生成」を参照してください。

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

次の手順

関数の名前付けのベストプラクティスについて説明するか、前に説明した手書き JSON メソッドを使用して関数をローカライズする方法を確認します。

次の方法で共有

カスタム関数の JSON メタデータを手動で作成する

メタデータの作成とマニフェストへの接続

JSON メタデータの例

メタデータリファレンス

allowCustomDataForDataTypeAny

allowErrorForDataTypeAny

functions

options

parameters

result

関数名を JSON メタデータに関連付ける

次の手順

関連項目

その他のリソース

次の方法で共有

カスタム関数の JSON メタデータを手動で作成する

メタデータの作成とマニフェストへの接続

JSON メタデータの例

メタデータ リファレンス

allowCustomDataForDataTypeAny

allowErrorForDataTypeAny

functions

options

parameters

result

関数名を JSON メタデータに関連付ける

次の手順

関連項目

その他のリソース

メタデータリファレンス