最終更新日 2024年02月06日(火)

この技術的なベストプラクティスの一覧は、アドオン統合を構築する場合に発生する可能性のある一般的なシナリオを処理する方法に関するガイダンスを提供します。アドオンの構築についての詳細は、Dev Center の「アドオンの構築​」のセクションを参照してください。

プラン変更の処理はべき等にする必要がある

アドオンがすでに使用している同じプランにアップグレードまたはダウングレードするためのリクエストが実行された場合、それはノーオペレーションとして処理する必要があります。200 OK​のレスポンスステータスコードを返し、自分でそれをログに記録しておきます。これが頻繁に発生する場合は、Heroku がアクションは失敗したとみなし、そのためにユーザーがそのアクションを再試行している、初期のプラン変更での問題を表している可能性があります。この状況を監視し、同じプランに変更するためのリクエストをべき等として処理することが最適なアプローチです。

高コストのプロビジョニングまたはプラン変更をリアルタイムに実行しない

プロビジョニングに数秒を超える時間がかかる場合は、非同期パートナー API​ を使用します。 プラン変更に数秒を超える時間がかかる場合、サービスは 202 Accepted​ ステータスコードで応答する必要があります。サービスが完了したときに環境変数への何らかの必要な変更を行うには、コールバック API を使用します。詳細は、アドオンパートナー API の概要​を参照してください。

古い識別子の代わりにアドオンリソース UUID を使用する

アプリのプライマリキーとしてリソース UUID を使用します。Heroku ID (または HID) などの古い識別子は使用しないでください。

プロビジョニングリクエスト​とアプリ情報の取得 API​ での従来の識別子は下位互換性のために存在します。サポートしている不変の (または、常に一定の) 識別子はリソース UUID だけです。これは、プロビジョニングリクエストでは uuid​ フィールド、アプリ情報の取得 API レスポンスでは resource.uuid​ フィールドです。

アドオン環境設定はアプリケーションに関連している必要がある

実行時にアプリケーションに対して有効であり、適切なクライアントライブラリまたはツールに役立つ環境設定のみを設定します。たとえば、SMTP などのサービスのユーザー名/パスワードを設定することは適切である可能性があります。ただし、ダッシュボードのユーザー名/パスワードは設定しないでください (これは SSO で処理する必要がある)。

使用する環境設定をできるだけ少なくしてください。すべてのメタデータが URI として自然に表される場合は、その URI を使用します。たとえば、DATABASE_USER​、DATABASE_HOST​、DATABASE_PASS​ ではなく、DATABASE_URL​ とします。

顧客の正しいメールアドレスを使用する

顧客にメールを送信するたびに、アプリの所有者または共同作業者のメールアドレスをフェッチしてください。顧客はこのメールアドレスを変更することを許可されており、アプリの所有者もこれを変更できるため、それをシステム内に保持しないことをお勧めします。

従来の (V1) アドオン統合を使用している場合は、アプリ情報の取得 API​ を使用する必要があります。現在の (V3) 統合を使用している場合は、「Syncing user access as an ecosystem partner​」(エコシステムパートナーとしてのユーザーアクセスの同期) ガイドに従うことができます。

プロビジョニングリクエストの id​ キーをメールアドレスとして使用しないでください。それは app123@heroku.com​ のようになります。これは、下位互換性のために保持している、Heroku ID (または HID) と呼ばれる従来の識別子です。これはメールアドレスとして機能しません。

SSO 経由で送信されたユーザーの特定

SSO 経由でダッシュボードにアクセスしているユーザーを特定するには、SSO のドキュメント​に従ってください。

SSO リクエストで指定されたユーザーメールアドレスが、アプリの所有者のメールアドレスでない可能性があることに注意してください。アプリでは複数の共同作業者がサポートされており、Heroku Enterprise では 1 つの組織にアプリのアドオンにアクセスできる複数のロールがあります。

一部のユーザーには、それぞれにアドオンを含む複数のアプリが割り当てられます。一部のパートナーは、メールアドレスを共有しているため、複数のインストールをマージしようとします。ただし、アプリは他のアカウントに移動できるため、そうしないことをお勧めします。

アプリ名は可変である

アプリ名は変更されます。ユーザーは、アプリの名前を変更できます。アドオンの請求アプリ名が必要な場合は常に、アプリ情報の取得 API​ を使用してそれをフェッチすることをお勧めします。将来は、ユーザーのリクエストでアプリ間でのアドオンの移動を許可する可能性があることに注意してください。アドオンレコードを自分で Heroku アプリまたはその名前に結び付けないことが最善です。

アタッチ可能なアドオンは複数のアプリにアタッチできる

コード内で、アドオンには 1 つの Heroku アプリしかアタッチされないことを前提としないように注意してください。特に、アプリ情報の取得 API​ からのアプリ名をアドオンの識別子として使用しないでください。これを行うと、設計が脆弱になり、アタッチ可能なアドオンまたはアプリあたり複数のアドオンを実装できなくなります。代わりに、コード内のアプリではなく、プロビジョニングリクエスト​とアプリ情報の取得 API​ から返されるアドオンリソースの UUID を常に参照する必要があります。

アドオン slug とプラン slug は変更できない

データの一貫性のために、特に請求期間中は、アドオン slug またはプラン slug への変更は許可されていません。代わりに、推奨されるプロセスでは、それを非表示または無効にして、推奨される名前で新しいプランを作成することによって既存のプランをアーカイブします。

質問および提案

この記事に含めた方がよいベストプラクティスに関する質問または提案がある場合は、サポートチケット​を開いてご連絡ください。