'クイックスタート: Heroku Connect API'

最終更新日 2024年05月08日(水)

低料金プラン​を使用してこのチュートリアルを完了することをお勧めします。資格のある学生の皆様は、新しい Heroku for GitHub Students プログラム​を通じてプラットフォームクレジットを申請できます。

Heroku Connect​ は、Salesforce と Heroku PostgreSQL データベース間の同期操作の作成、保守、監視を自動化するための API を提供します。このガイドは、その API を介して Heroku Connect の使用を開始するために役立ちます。

前提条件

このガイドでは、次のことを前提としています。

  • 確認済みの Heroku アカウント
  • Heroku CLI​ プラグインがインストールされていること。
  • Heroku Platform API 直接認証​トークンがあること。このトークンを使用して Heroku Connect API 呼び出しを認証します。このベアラートークンは、独自アプリケーションの Heroku ユーザー専用です。Heroku Connect では、他の Heroku ユーザーの代理として API にアクセスすることはサポートされていません。

手順 1: Heroku アプリと Heroku Postgres データベースを作成する

Heroku Connect では、Salesforce からデータを同期するために Heroku Postgres​ が必要です。Heroku Connect と Heroku Postgres はどちらもアドオンであり、Heroku アプリにアタッチする必要があります。空のアプリにアドオンをアタッチすることができ、コードのデプロイは必要はありません。

データベースを使用してこのチュートリアルを完了した場合、使用量のカウントに入ります。コストを抑制するために、完了したらすぐにデータベースを削除してください。低料金プラン​について確認してください。資格のある学生の皆様は、Heroku for GitHub Students プログラム​を通じてプラットフォームクレジットを申請できます。

次のようにして、空のアプリを作成して Heroku Postgres をアタッチします。

  1. Heroku CLI コマンド​: ​heroku apps:create​ を使用してアプリを作成します。
  2. Heroku CLI コマンド​: ​heroku addons:create heroku-postgresql:PLAN_NAME​ を使用してデータベースをプロビジョニングします。プラン名を指定しない場合、essential-0​ プランがプロビジョニングされますが、このデフォルトはお勧めしません。本番稼働のユースケースでは -4​ 以上のプランを選択してください。詳細は、「Heroku Connect​」を参照してください。チュートリアルの目的に限り、費用を最小限に抑えるために essential-0​ プランを選択できます。

手順 2: Heroku Connect アドオンをプロビジョニングする

次の Heroku CLI コマンド​: ​heroku addons:create herokuconnect:PLAN_NAME​ を実行します。

プラン名を指定しない場合、demo​ プランがプロビジョニングされます。詳細は、使用可能なプラン​に関する項目を参照してください。

手順 3: Heroku Connect にユーザーを追加する

直接承認 (ベアラー) トークンを取得する手順は、「OAuth​」を参照してください。

デフォルトでは、Heroku Connect アドオンにユーザーは存在しません。次のエンドポイントを使用して、Heroku ユーザーアカウントをアクセスリストに追加します。

POST https://hc-central.heroku.com/auth/<app_name_or_app_uuid>

次に例を示します。

$ curl -X POST https://hc-central.heroku.com/auth/example-app \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

これにより、最新の接続を含め、アクセスできるすべてのリージョンのすべての​ Connect アドオンが返されます。jq​などのツールで応答をフィルタリングできます。

応答の例:

{"user": {"id": "86fa36aa-a8de-4b97-8c5b-6dcfb44180ad", "email": "example-user@example.com"}, "connections": [{"id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4", "resource_name": "herokuconnect-defined-93233"...}

手順 4: 後続の API 呼び出し用の接続情報をメモする

前の手順を完了して受け取った応答には region_url​ が含まれています。 この region_url​ の末尾に /api/v3​ を追加すると、接続のルートとなる Heroku Connect API v3 URL が得られます。このルート URL は、これ以降の Heroku Connect API リクエストに使用します。詳細は、「ルートエンドポイント​」を参照してください。複数の接続がある場合は、作成した新しい接続の情報を必ずメモしておいてください。

このガイドの例では、アプリが Virginia (バージニア) リージョンにあり、ルート API URL が https://connect-3-virginia.heroku.com/api/v3​ であると想定します。

応答には、新しく作成した接続の接続 id​ も含まれています。後続の API 呼び出しで使用するために、この id​ をメモしておいてください。

手順 5: データベースとスキーマを設定する

データベースの環境設定名と、Salesforce データを格納するための未使用のスキーマ名を使用して接続を設定します。通常、これらの値は DATABASE_URL​ と salesforce​ です。

これらの値を設定するには、PATCH 呼び出しを送信します。db_key​はデータベース環境設定に対応します。前の手順でメモした、接続の id​ の値をエンドポイントに使用します。

PATCH /connections/<connection_id>

次に例を示します。

$ curl -X PATCH https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4 \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json" \
-d '{"schema_name": "salesforce", "db_key": "DATABASE_URL"}'

応答の例:

{
  "id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
  "name": "example-app",
  "resource_name": "herokuconnect-defined-93233",
  "schema_name": "salesforce",
  "db_key": "DATABASE_URL",
  ...
}

手順 6: Salesforce 組織への接続を認証する

承認 URL を取得して、Salesforce 組織と通信する Heroku Connect を認証します。Salesforce ユーザーがこの URL を開いて認証を完了します。一般的なアプリケーションでは、承認 URL を取得し、ユーザーに表示するボタンにその URL をリンクすることができます。

POST /connections/<connection_id>/authorize_url

次に例を示します。

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/authorize_url \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json" \
-d '{"environment": "production"}'

応答の例: term {"redirect": "https://connect-3-virginia.heroku.com/oauth/start/…"}

その redirect​ フィールドの URL にアクセスして認証を完了します。

すべての使用可能な JSON パラメータはここ​で確認できます。

プログラムによってこの手順を完了する方法はありません。Salesforce 認証では、この URL に手動でアクセスし、Heroku と Salesforce の両方に認証されることが要求されます。

手順 7: マッピング設定をエクスポートする

マッピングを作成して、Salesforce から同期するオブジェクトとフィールドを設定します。これを行うには、既存の設定をインポートするのが最も簡単です。

マッピングが設定されている既存の Heroku Connect 接続がある場合、その設定を JSON としてエクスポートし、新しい接続にインポートすることができます。別の既存の接続がない場合は、手順 9​ までスキップしてください。

Heroku Connect ダッシュボードから設定ファイルをエクスポート​するか、次のように API を使用してエクスポートすることができます。

POST /connections/<connection_id>/actions/export

次に例を示します。

curl -X GET https://connect-3-virginia.heroku.com/api/v3/connections/1ac07199-0ddb-43e9-9865-8d9721ca6c6e/actions/export \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
--output config.json

この例では、--output​ を使用して JSON 応答を config.json​ ファイルに保存します。使用する接続 ID が他の手順と異なるのは、別の接続の設定をエクスポートするためです。

--output​ を使用しない場合の応答の例は次のとおりです。

{"mappings":[{"object_name":"Account","config":{"access":"read_write","sf_notify_enabled":false,"sf_polling_seconds":600,...}

手順 8: マッピング設定をインポートする

次のエンドポイントを使用して設定ファイルをインポートします。

POST /connections/<connection_id>/actions/import

このエンドポイントには、標準のファイルアップロードとして、またはリクエスト本体で JSON として直接、設定の詳細を渡すことができます。

次に例を示します。

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/actions/import \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-F "config=@config.json"

または

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/actions/import \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json"  \
-d @config.json

応答でエラーが示されていない場合、手順 10​ に進んで接続とマッピングのステータスを確認します。

手順 9: マッピングを作成する

手順 7 と 8 で設定ファイルをエクスポートおよびインポートした場合は、追加のマッピングを作成しない限り、この手順をスキップできます。

このエンドポイントを使用すれば、設定全体を一度にインポートできることに加えて、1 つのマッピングを既存の接続に一度に追加できます。

POST /connections/<connection_id>/mappings

この API エンドポイントの JSON ペイロードには、マッピング自体の詳細な設定が含まれています。

次の例のペイロードは、Account オブジェクトの特定のフィールドを同期する読み取り/書き込みマッピングを設定します。

次に例を示します。

curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/mappings \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H 'Content-Type: application/json' \
-d @- << EOF
{
  "object_name": "Account",
  "config": {
    "access": "read_write",
    "sf_notify_enabled": true,
    "sf_polling_seconds": 600,
    "fields": {
      "CreatedDate": {},
      "Id": {},
      "IsDeleted": {},
      "Name": {},
      "SystemModstamp": {}
    },
    "indexes": {
      "Id": {
        "unique": false
      },
      "SystemModstamp": {
        "unique": false
      }
    }
  }
}
EOF

この API リクエストに想定されるペイロードについての詳細は、マッピングの作成​に関する項目を参照してください。

応答の例:

{"id":"19f75004-8383-426e-9f33-5a811f5c8f78","_id":213914,"object_name":"Account","state":"SCHEMA_CHANGED","config":{"access":"read_write"...}

この手順は、同期する Salesforce オブジェクトの数と同じ回数まで繰り返すことができます。

手順 10: 接続とマッピングのステータスを監視する

接続詳細 API エンドポイントを使用します。

GET /connections/<connection_id>

deep​ クエリ文字列パラメータを使用すると、接続自体のほかに、接続のマッピングについての情報も返されます。

次に例を示します。

$ curl -X GET "https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4?deep=true" \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

応答には、接続とマッピングについての詳細情報が含まれています。接続とマッピングの状態をチェックして、想定通りに動作していることを確認します。詳細は、「接続状態リファレンス​」および「マッピング状態のリファレンス​」の記事を参照してください。

応答の例:

{
  "id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
  "name": "example-app",
  "resource_name": "herokuconnect-defined-93233",
  "schema_name": "salesforce",
  "db_key": "DATABASE_URL",
  "state": "IDLE",
  "mappings": [
    {
      "id": "7b5a2105-9845-43cd-9648-9406ee745bf5",
      "object_name": "Account",
      "state": "DATA_SYNCED",
      …
    },
    {
      "id": "3f87cb43-2b2b-4a40-a396-d3611cb776b4",
      "object_name": "Contact",
      "state": "DATA_SYNCED",
      …
    },
    …
  ]
  …
}

次のステップ

このチュートリアルでは、空の Heroku アプリをセットアップします。このアプリにコードをデプロイするには、デプロイ​に関する記事を参照してください。ほとんどのユーザーは Git​ を使用してコードをデプロイします。

Heroku アプリから Heroku Postgres データベースに接続するには、「Heroku Postgres​」を参照してください。

外部接続から Heroku Postgres に接続するには、「外部接続 (ingress)​」および「Private Space と Shield Space での Heroku Postgres​」を参照してください。

実行できるその他の API 操作については、「Heroku Connect API​」を参照してください。