アプリケーションライフサイクル管理 (ALM) API

[アーティクル]
04/08/2023

ALM API は、テナント全体で SharePoint Framework ソリューションとアドインの展開を管理するためのシンプルな API を提供します。 ALM API でサポートされる機能は次のとおりです。

テナントまたはサイトコレクションのアプリカタログに SharePoint Framework ソリューションまたは SharePoint アドインを追加します。
テナントまたはサイトコレクションのアプリカタログから SharePoint Framework ソリューションまたは SharePoint アドインを削除します。
テナントまたはサイトコレクションのアプリカタログにインストールできるように、SharePoint Framework ソリューションまたは SharePoint アドインを有効にします。
テナントまたはサイトコレクションのアプリカタログにインストールできないように、SharePoint Framework ソリューションまたは SharePoint アドインを無効にします。
テナントまたはサイトコレクションのアプリカタログからサイトに SharePoint Framework ソリューションまたは SharePoint アドインをインストールします。
サイトの SharePoint Framework ソリューションまたは SharePoint アドインをアップグレードします (テナントまたはサイトコレクションのアプリカタログで使用可能な新しいバージョンがある場合)。
サイトから SharePoint Framework ソリューションまたは SharePoint アドインをアンインストールします。
テナントまたはサイトコレクションのアプリカタログ内の SharePoint Framework ソリューションまたは SharePoint アドインを一覧表示して詳細を取得します。

ALM API は、UI から実行できる操作とまったく同じ操作を実行する際に使用できます。この API を使用すると、すべての一般的な処理が実行されます。次に、ALM API の特徴をいくつか示します。

Install と UnInstall イベントは、対応する操作が発生したときにプロバイダー向けのホスト型アドインに向けてトリガーされます。
ALM API は、SharePoint Framework ソリューションでのみアプリベースの操作をサポートします。

ALM API は、テナントを対象としたサイトコレクションとサイトコレクションアプリカタログをサポートします。特定のアプリカタログを対象とする場合は、対応するアプリカタログの URL を使用します。このページで説明するアクションを含むサイトコレクションのアプリカタログを対象にする前に、有効にする必要があります。

重要

テナント管理用のアクセス許可を必要とするテナントスコープのアクセス許可は、ALM API ではサポートされません。

ALM API の操作に関する詳細オプション

ALM API は、REST API を使用することでネイティブに提供されますが、SharePoint PnP コミュニティチャネルを通じて追加のクライアントオブジェクトモデル (CSOM) 拡張機能、PowerShell コマンドレット、クロスプラットフォームの CLI for Microsoft 365 も使用できます。

SharePoint REST API

ALM API は、SharePoint REST API のエンドポイントとしてネイティブに提供されています。

以下に示す例のように、REST API を使用する場合は、すべての HTTP 要求にアプリカタログを含める必要があります。エンドポイントで {app-catalog-scope} プレースホルダーをアプリカタログの範囲に置き換えます。利用可能なスコープオプションは、tenantappcatalog および sitecollectionappcatalog です。

次に例を示します。

範囲	Endpoint
tenant	`https://contoso.sharepoint.com/sites/AppCatalog/_api/web/tenantappcatalog/{command}`
サイトコレクション	`https://contoso.sharepoint.com/sites/Marketing/_api/web/sitecollectionappcatalog/{command}`

https://contoso.sharepoint.com/sites/AppCatalog にあるテナントのアプリカタログを対象とする場合、エンドポイントは ** になります

詳細情報はこちら: SharePoint REST API

PnP CSOM (別名: PnP Sites Core)

PnP CSOM は、SharePoint REST API を呼び出して ALM API を実装します。

PnP CSOM で ALM API を使用する前に、Microsoft.SharePointOnline.CSOM を使用して、認証済みのクライアントコンテキストを取得する必要があります。次に、認証されたクライアントコンテキストを使用して、PnP CSOM の AppManager オブジェクトのインスタンスを取得し、ALM コマンドを呼び出します。

using Microsoft.SharePoint.Client;
using OfficeDevPnP.Core.ALM;

// ...

using (var context = new ClientContext(webURL)) {
  context.Credentials = new SharePointOnlineCredentials(username, securePassword);
  var appManager = new AppManager(context);
  // execute PnP CSOM ALM command
}

PnP Core のすべてのメソッドでは、要求が SharePoint CSOM ClientContext オブジェクトを使用して接続するテナントのアプリカタログを対象にすることを想定しています。オプションの scope 引数を使用して、すべてのコマンドの範囲を上書きすることができます。例

appManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx', AppCatalogScope.Site);

詳細情報はこちら: PnP PowerShell

PnP PowerShell

PnP PowerShell は、PnP CSOM を呼び出して ALM API を実装します。

PnP PowerShell モジュールのいずれかのコマンドレットを使用する前に、まず Connect-PnPOnline コマンドレットを使用して SharePoint Online に接続する必要があります。

PowerShell のすべてのコマンドレットでは、要求が Connect-PnPOnline コマンドレットを使用して接続するテナントのアプリカタログを対象にすることを想定しています。 -Scope パラメーターを使用してコマンドの範囲をオーバーライドし、サイトコレクションアプリカタログを対象にすることができます。

詳細情報はこちら: PnP PowerShell

注:

PnP PowerShell はオープンソースソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープンソースツールのサポート SLA はありません。

CLI for Microsoft 365

CLI for Microsoft 365 は、Windows、MacOS、Linux などのあらゆるプラットフォームで使用できるクロスプラットフォームコマンドラインインターフェイスです。 CLI は、SharePoint REST API を呼び出して ALM API を実装します。

CLI for Microsoft 365 でコマンドを使用する前に、まず m365 login コマンドを使用して、Microsoft 365 テナントに接続する必要があります。

詳細情報はこちら: CLI for Microsoft 365

注:

CLI for Microsoft 365 はオープンソースソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープンソースツールのサポート SLA はありません。

ソリューションパッケージを追加する

まず、アプリパッケージ (*.sppkg または *.app) をアプリカタログに追加して、SharePoint サイトで使用できるようにします。

HTTP 要求

POST /_api/web/{scope}appcatalog/Add(overwrite=true, url='sharepoint-solution-package.sppkg')

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
Content-Type	`application/json`
X-RequestDigest	`{form digest}`
binaryStringRequestBody	`true`

要求本文

ファイルのバイト配列

// read file
var filePath = "c:\path\to\file\sharepoint-solution-package.sppkg";
// get an instance of the PnP CSOM's AppManager as shown above
var result = appManager.Add(filePath);

Add-PnPApp -Path ./sharepoint-solution-package.sppkg

m365 spo app add --filePath ./sharepoint-solution-package.sppkg

ソリューションパッケージを展開する

ソリューションを展開することで、サイトにインストールできるようになります。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
Content-Type	`application/json;odata=nometadata;charset=utf-8`
X-RequestDigest	`{form digest}`

要求本文

{
  "skipFeatureDeployment": true
}

注:

この操作は、Add エンドポイントを呼び出した後、特定のサイトにパッケージをインストールする前にのみ行うことができます。

重要

複数のパッケージを並行して展開することはサポートされていません。展開操作をシリアル化して、展開エラーを防いでください。

appManager.Deploy('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Publish-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app deploy --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

ソリューションパッケージを取り消す

これは、上記の展開手順の逆です。ソリューションを取り消すと、サイトにインストールすることはできません。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
X-RequestDigest	`{form digest}`

注:

この操作により、サイトでのソリューションのインストールがブロックされ、既存のインストールが無効になります。

// get an app package
appManager.Retract('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Unpublish-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app retract --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

ソリューションパッケージを削除する

これは、上記の追加手順の逆です。アプリカタログから削除されると、そのソリューションは展開できません。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove

appManager.Remove('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Remove-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app remove --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

注:

取り消しの操作が削除の操作の前に実行されていない場合は、ソリューションの取り消しが自動的に行われます。

利用可能なパッケージのリストの作成

この操作では、アプリカタログで利用可能な SharePoint Framework ソリューションまたは SharePoint アドインのリストを返します。

HTTP 要求

GET /_api/web/{scope}appcatalog/AvailableApps

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`

応答

{
  "value": [
    {
      "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "ContainsTenantWideExtension": false,
      "CurrentVersionDeployed": true,
      "Deployed": true,
      "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "IsClientSideSolution": true,
      "IsEnabled": true,
      "IsPackageDefaultSkipFeatureDeployment": false,
      "IsValidAppPackage": true,
      "ShortDescription": "",
      "SkipDeploymentFeature": false,
      "Title": "sharepoint-solution-package"
    },
    {
      "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "ContainsTenantWideExtension": false,
      "CurrentVersionDeployed": true,
      "Deployed": true,
      "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "IsClientSideSolution": true,
      "IsEnabled": true,
      "IsPackageDefaultSkipFeatureDeployment": false,
      "IsValidAppPackage": true,
      "ShortDescription": "",
      "SkipDeploymentFeature": false,
      "Title": "sharepoint-solution-package2"
    }
  ]
}

var allAppPackages = appManager.GetAvailable();

Get-PnPApp

m365 spo app list

特定のソリューションを取得する

この操作は、アプリカタログ内の利用可能な SharePoint Framework ソリューションまたは SharePoint アドインの詳細を返します。

HTTP 要求

GET /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`

応答

{
  "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "ContainsTenantWideExtension": false,
  "CurrentVersionDeployed": true,
  "Deployed": true,
  "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "IsClientSideSolution": true,
  "IsEnabled": true,
  "IsPackageDefaultSkipFeatureDeployment": false,
  "IsValidAppPackage": true,
  "ShortDescription": "",
  "SkipDeploymentFeature": false,
  "Title": "sharepoint-solution-package"
}

var appPackage = appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');

Get-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app get --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

ソリューションパッケージをサイトにインストールする

アプリカタログから特定の ID を持つソリューションパッケージを、URL コンテキストに基づいてサイトにインストールします。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
X-RequestDigest	`{form digest}`

// get an app package
appManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Install-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app install --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

インストール済みソリューションパッケージのアップグレード

ソリューションパッケージをサイトから、アプリカタログで利用可能な新しいバージョンにアップグレードします。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
X-RequestDigest	`{form digest}`

// get an app package
var appPackage = appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');
if (appPackage.CanUpgrade) {
  appManager.Upgrade(appPackage)
}

Update-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app upgrade --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

サイトからソリューションパッケージをアンインストールする

この操作は、上記のインストールコマンドの逆です。

注:

以下のいずれかの方法で、サイトからソリューションパッケージをアンインストールする場合、そのパッケージは完全に削除され、ごみ箱に配置されることはありません。

HTTP 要求

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Uninstall

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
X-RequestDigest	`{form digest}`

appManager.Uninstall('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Uninstall-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

m365 spo app uninstall --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

ソリューションをMicrosoft Teams App Catalogに同期させます

この操作ではアプリカタログサイトでソリューションのリストアイテム ID を参照する必要があります。

HTTP 要求

POST /_api/web/{scope}appcatalog/SyncSolutionToTeams(id=xxxxx)

要求ヘッダー

ヘッダー	値
Authorization	`Bearer {token}`
承諾	`application/json;odata=nometadata`
X-RequestDigest	`{form digest}`

appManager.SyncToTeams('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Sync-PnPAppToTeams -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

アプリケーション ライフサイクル管理 (ALM) API

ALM API の操作に関する詳細オプション

SharePoint REST API

PnP CSOM (別名: PnP Sites Core)

PnP PowerShell

CLI for Microsoft 365

ソリューション パッケージを追加する

HTTP 要求

要求ヘッダー

要求本文

ソリューション パッケージを展開する

HTTP 要求

要求ヘッダー

要求本文

ソリューション パッケージを取り消す

HTTP 要求

要求ヘッダー

ソリューション パッケージを削除する

HTTP 要求

利用可能なパッケージのリストの作成

HTTP 要求

要求ヘッダー

応答

特定のソリューションを取得する

HTTP 要求

要求ヘッダー

応答

ソリューション パッケージをサイトにインストールする

HTTP 要求

要求ヘッダー

インストール済みソリューション パッケージのアップグレード

HTTP 要求

要求ヘッダー

サイトからソリューション パッケージをアンインストールする

HTTP 要求

要求ヘッダー

ソリューションをMicrosoft Teams App Catalogに同期させます

HTTP 要求

要求ヘッダー

関連項目

その他のリソース

アプリケーションライフサイクル管理 (ALM) API

ソリューションパッケージを追加する

ソリューションパッケージを展開する

ソリューションパッケージを取り消す

ソリューションパッケージを削除する

ソリューションパッケージをサイトにインストールする

インストール済みソリューションパッケージのアップグレード

サイトからソリューションパッケージをアンインストールする