ファイル ハンドラー 2.0 のアクションを指定する

  • [アーティクル]

ファイル ハンドラーの登録時には、そのファイル ハンドラーで有効になるアクションのセットを指定します。

次に示す 3 つの組み込みのアクションは、ファイル ハンドラーでサポートすることを選択できます。

  • newFile: OneDrive および SharePoint の [新規] メニューに表示されるファイルの種類。
  • open: ファイル ハンドラーで開くことができるファイル。OneDrive および SharePoint の [開く] メニューに表示されます。 開くアクションは、新しいブラウザー タブで起動されます。
  • preview: ファイル ハンドラーでプレビューできるファイル。 プレビューは、OneDrive および SharePoint で、ユーザーがファイルを左クリックしたときに実行されます。 プレビュー アクションは、OneDrive および SharePoint の Web サイトの <IFRAME> 要素内に読み込まれます。

追加のファイル ハンドラーにより、アプリケーションで定義したアクションをファイル ハンドラーで実行できるようにする、custom アクション タイプをサポートします。 これに該当する追加のアクションは、OneDrive および SharePoint のツール バーに表示され、任意のファイル拡張子に追加できます。

ファイル ハンドラー マニフェストでアクションを定義する

アクションは、ファイル ハンドラー マニフェストの actions キー/値ペアで定義されます。これには、ファイル ハンドラーでサポートされるアクションの配列が含まれます。

次に、3 つの組み込みアクションと 1 つのカスタム アクションの定義例を示します。

[
    {
        "type": "newFile",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "open",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "preview",
        "url": "https://url/for/endpoint",
        "availableOn": {
            "file": { "extensions": [".bin"] },
            "web": { }
        }
    },
    {
        "type": "custom",
        "url": "https://url/for/endpoint",
        "displayName": "Add Signature with Contoso",
        "shortDisplayName": "Add Signature",
        "icon": {
            "png1x": "https://url/for/icon.png"
        },
        "availableOn": {
            "file": { "extensions": ["*"] },
            "folder": { },
            "allowMultiSelect": true,
            "web": { }
        }
    }
]

Azure Active Directory アドイン拡張機能の制限により、これらのアクションは文字列にシリアル化されて保管されます。 マニフェストに保管するために文字列値に変換する前に、配列を JSON 形式で縮小するようにしてください。

たとえば、前述のアクションの定義は、次のようにしてファイル ハンドラー マニフェストに保管します。

{
    "type": "FileHandler",
    "properties": [
        {
            "key": "version",
            "value": "2"
        },
        {
            "key": "actions",
            "value": "[{\"type\":\"newFile\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"open\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"preview\",\"url\":\"https://url/for/endpoint\",\"availableOn\":{\"file\":{\"extensions\":[\".bin\"]},\"web\":{}}},{\"type\":\"custom\",\"url\":\"https://url/for/endpoint\",\"displayName\":\"Add Signature with Contoso\",\"shortDisplayName\":\"Add Signature\",\"icon\":{\"png1x\":\"https://url/for/icon.png\"},\"availableOn\":{\"file\":{\"extensions\":[\"*\"]},\"folder\":{},\"allowMultiSelect\":true,\"web\":{}}}]"
        }
    ]
}

アクション パラメーター

アクション パラメーターで宣言した各アクションは、次に示す形式になります。

{
    "type": "newFile | open | preview | custom",
    "url": "url",
    "displayName": "string",
    "shortDisplayName": "string",
    "icon": { 
        "@odata.type": "microsoft.graph.displayIcon",
        "svg": "url",
        "png1x": "url",
        "png1_5x": "url",
        "png2x": "url"
    },
    "availableOn": {
        "@odata.type": "microsoft.graph.availableOn",
        "file": {
            "@odata.type": "microsoft.graph.availableOnFile",
            "extensions": [ ".pdf", ".png", ".psd" ]
        },
        "folder": {
            "@odata.type": "microsoft.graph.availableOnFolder"
        },
        "allowMultiSelect": false,
        "web": { "@odata.type": "microsoft.graph.availableOnWeb" }
    }
}

プロパティ

すべてのプロパティが必要なわけではありません。指定したアクションの種類によって異なります。

パラメーター名 型 説明
type string newFile、open、または preview の値。 必須。
url URL ファイル ハンドラーのアクションを処理するエンドポイントの https:// URL。 必須。
displayName string アクションを表すために type: "custom" に使用される、既定のロケールの文字列。 省略可能。
shortDisplayName string ツールバーまたは折りたたまれたアクション メニュー内のアクションを表すために type: "custom" に使用される、既定のロケール文字列。 省略可能。
availableOn オブジェクト このアクションが使用可能になる状況を定義する、プロパティのコレクション。 必須。
アイコン displayIcon このファイルの種類のアイコン イメージへの URL を含むオブジェクト。 省略可能。
  • displayName プロパティは、アクションの種類が custom の場合にのみ適用され、その他の種類のアクションでは無視されます。

AvailableOn プロパティ

availableOn プロパティ内のプロパティを設定することで、アクションを使用できる場所をカスタマイズできます。

パラメーター名 型 説明
file.extensions 文字列の配列 アクションが使用可能になる、ファイル拡張子の配列。 ファイル拡張子は、ピリオド (.) で始まる必要があります。 ワイルドカード文字 * は、カスタム アクションがすべてのファイル拡張子に対応することを示すために使用できます。
folder オブジェクト パラメーターのないオブジェクトは、フォルダーが選択されているとき、またはファイルが選択されていないときに、ファイル ハンドラーが使用可能になることを示します。 null 値またはプロパティが定義されていない場合は、このアクションがフォルダーに対して使用できないことを示します。
allowMultiSelect boolean true の場合、複数のファイルの選択が可能になり、アクションが表されたままになります。 false または指定なしの場合、アクションは 1 つのアイテムが選択されているときにのみ表示されます。
web オブジェクト パラメーターのないオブジェクトは、Web サイトを閲覧しているときにファイル ハンドラーが使用可能になることを示します。
  • アクションの種類が newFile の場合、指定できるファイル拡張子は 1 つのみです。 これは、新しく作成されるファイルに付けられる拡張子です。 複数のファイル拡張子がリスト表示された場合は、最初のファイル拡張子が使用されます。
  • folder プロパティと allowMultiSelect プロパティは、アクションの種類が custom の場合にのみ適用されます。 これらの値は、その他の種類のアクションでは無視されます。