最終更新日 2023年08月28日(月)

Heroku Connect​ は、Salesforce と Heroku PostgreSQL データベース間の同期操作の作成、保守、監視を自動化するための API を提供します。

バージョン情報

Heroku では、Heroku Connect API のバージョン 3 がサポートされています。Heroku では、互換性ポリシー​に概略を示すように、API に加えた変更と新しい API バージョンを通知します。

はじめに

「クイックスタート: Heroku Connect API​」のチュートリアルを確認してください。このチュートリアルは、Heroku CLI および Heroku Connect API を使用して Heroku Connect を設定する手順を示します。

認証

Heroku Connect API には、Heroku Platform API 直接承認​トークンが必要です。このトークンは、独自アプリケーションの Heroku ユーザー専用です。Heroku Connect では、他の Heroku ユーザーの代理として API にアクセスすることはサポートされていません。

次のように、Authorization​ ヘッダーでこのトークンを指定します。

Authorization: Bearer <token>

Heroku Connect アクセスリストにユーザーを追加する

デフォルトでは、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​ などのツールでデータをフィルタリングできます。このデータには region_url​ が含まれています。この region_url​ の末尾に /api/v3​ を追加すると、接続のルートとなる Heroku Connect API v3 URL が得られます。詳細は、「ルートエンドポイント​」を参照してください。

リクエストメソッド

ほとんどの Heroku Connect API は、GET​ または POST​ のいずれかのリクエストに応答します。PUT​、DELETE​、PATCH​ などの他のメソッドを使用する場合もあります。これらのメソッドはほとんどの HTTP ライブラリでサポートされますが、Force.com プラットフォーム上の Apex コードなどの一部の環境では、一部のサブセットしかサポートされません。これらの追加エンドポイントを使用するために、必要な HTTP メソッドを示す追加ヘッダーと共に POST​ リクエストを使用することができます。

    X-HTTP-Method-Override: PATCH

JSON エンコードされたリクエストのペイロードと応答

POST​/PATCH​ リクエストのペイロードとすべての API 応答は、JSON エンコードされています。これらのリクエストには、Content-Type​ ヘッダーを指定します。

    Content-Type: application/json

速度制限

API には、1 接続、1 日あたり 5,000 リクエストの速度制限があります。この制限に達した後に API へのアクセスを試みると、結果は 429 Too Many Requests​ になります。応答メッセージには、新しい API リクエストを作成できると考えられるタイミングも表示されます。

{"message":"Request was throttled. Expected available in 72170 seconds."}

ルートエンドポイント

Heroku Connect は、それぞれが異なるドメインで応答する多くのリージョンで動作します。ルート API URL は次のとおりです。

アプリが稼働するリージョンに対応する API エンドポイントを使用する必要があり​、これは Heroku CLI​ を使用して確認できます。

$ heroku info -a <app_name>
=== <app_name>
Git Url:       git@heroku.com:<app_name>.git
Web Url:       https://<app_name>-<random-identifier>.herokuapp.com/
Addons:        heroku-postgresql:standard-0
               herokuconnect:enterprise
…
Region:        us
…

アプリの集中拠点のエンドポイントプレフィックスを選択してください。ユーザーのニーズが複数のリージョンに拡張した場合、後で変更することができます。

接続エンドポイント

これらのエンドポイントを使用して、情報を入手し接続の維持に役立てます。

接続リストを取得する

アクセスできるすべての Heroku Connect 接続のリストと、詳細情報を取得します。

GET /connections

次に例を示します。

$ curl -X GET https://connect-3-virginia.heroku.com/api/v3/connections \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json"

応答の例:

{
   "count":1,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":"c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
         "_id":76070,
         "name":"",
         "addon_id":"c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
         "app_name":"example-app",
         "team_name":null,
         "app_id":"a63e5256-3c1c-4382-ba99-158fc63f8945",
         "schema_name":"salesforce",
         "db_key":"DATABASE_URL",
         "database":{
            "host":"ec2-34-194-215-27.compute-1.amazonaws.com",
            "database":"d6mah9u2hj7110",
            "port":5432
         },
         "organization_id":"00D4W0000054k3cUAA",
         "state":"POLLING_DB_CHANGES",
         "mappings_summary_state":"OK",
         "detail_url":"/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
         …
}

接続の詳細を取得する

ある特定の接続の詳細を取得します。 GET /connections/<connection_id>

次に例を示します。

$ 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",
      …
    },
    …
  ]
  …
}

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

接続のデータベースおよびスキーマを構成する

Heroku Postgres データベースと、Salesforce のデータを格納するために使用されるスキーマの名前を設定します。

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"
}

Salesforce 組織への接続を認証する

承認 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"}'

応答の例:

{"redirect": "https://connect-3-virginia.heroku.com/oauth/start/…"}

Salesforce ユーザーは、この URL を開いて認証を完了する必要があります。一般的なアプリケーションでは、承認 URL を取得し、ユーザーに表示するボタンにその URL をリンクすることができます。認証が完了すると、ユーザーは、next​ パラメーターに指定された URL (指定されていない場合は Heroku Connect ダッシュボード) にリダイレクトされます。

接続を一時停止する

POST /connections/<connection_id>/actions/pause

アクティブな接続を一時停止してデータの同期を止めます。

次に例を示します。

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

正常な応答には、202 HTTP ステータスコードが表示されます。接続の状態をチェック​して、PAUSED​ であることを確認します。

一時停止した接続は、関連するエンドポイント​を使用して再開できます。

接続を再開する

POST /connections/<connection_id>/actions/resume

一時停止した接続を再開します。

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

正常な応答には、202 HTTP ステータスコードが表示されます。接続の状態をチェック​して、PAUSED​ でないことを確認します。

接続を再起動する

接続はいつでも再起動できます。再起動すると、システムエラーがクリアされ、データの同期が再試行されます。エラーが解決している場合、接続は正常な状態に戻ります。解決していない場合、次にエラーが発生したときに、接続とそのマッピングがエラー状態に戻ることがあります。このアクションは、Heroku Connect ダッシュボードの Recover from error​ ボタンと同じです。

POST /connections/<connection_id>/actions/restart

次に例を示します。

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

正常な応答には、202 HTTP ステータスコードが表示されます。接続の詳細を取得​して、エラー状態でなくなっていることを確認します。

設定をエクスポートする

接続のマッピング設定を JSON にエクスポートできます。エクスポートした結果を別の接続にインポートして、そのマッピングを設定することができます。

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​ ファイルに保存します。

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

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

設定をインポートするエンドポイント​では、JSON ファイルと、リクエスト本体に直接送信された JSON を両方受け入れます。

設定をインポートする

接続のマッピングを設定する最も簡単な方法は、既存の設定をインポートすることです。既存の設定をエクスポート​し、このエンドポイントを使用してエクスポートした設定をインポートできます。

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

エラーが発生しない場合は、接続詳細エンドポイント​を使用してください。接続のマッピングの一覧を表示するには、クエリ文字列パラメーター deep​ を true​ に設定します。

マッピングエンドポイント

これらのエンドポイントを使用して、情報を入手しマッピングの維持に役立てます。

マッピングの一覧を取得する

接続のマッピングの一覧を取得するには、接続詳細エンドポイントを使用して、クエリ文字列パラメーター deep​ を true​ に設定します。このパラメーターを設定すると、接続のマッピングの一覧が id​ とともに返され、この記事に記載されている他のマッピングエンドポイントにも使用できます。詳細は、「接続の詳細を取得する​」を参照してください。

マッピングの詳細を取得する

マッピングについての詳細を取得します。

GET /mappings/<mapping_id>

次に例を示します。

$ curl -X GET https://connect-3-virginia.heroku.com/api/v3/mappings/7b5a2105-9845-43cd-9648-9406ee745bf5 \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

応答には、マッピングの設定の詳細、ステータス、関連情報を取得するための追加 URL が含まれています。

応答の例:

{
  "access": "read_only",
  "actively_writing": false,
  "config": {
    "access": "read_only",
    "fields": {
      "CreatedDate": {},
      "Id": {},
      "IsDeleted": {},
      "SystemModstamp": {}
    },
    "indexes": {
      "Id": {
        "unique": false
      },
      "SystemModstamp": {
        "unique": false
      }
    },
    "revision": 12345,
    "sf_notify_enabled": true,
    "sf_polling_seconds": 600
  },
  "connection": {
    "id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4"
  },
  "counts": {
    "db": 0,
    "errors": 0,
    "pending": 0,
    "sf": 0
  },
  "detail_url": "https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
  "id": "7b5a2105-9845-43cd-9648-9406ee745bf5",
  "object_name": "Account",
  "state": "DATA_SYNCED",
  "state_description": "OK",
  "times": {
    "db_poll": "<date>",
    "db_write": "<date>",
    "sf_poll": "<date>",
    "sf_write": "<date>",
  },
}

マッピングを作成する

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

POST /connections/<connection_id>/mappings

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

次に例を示します。

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_only",
    "sf_notify_enabled": true,
    "sf_polling_seconds": 600,
    "fields": {
      "CreatedDate": {},
      "Id": {},
      "IsDeleted": {},
      "Name": {},
      "SystemModstamp": {}
    },
    "indexes": {
      "Id": {
        "unique": true
      },
      "SystemModstamp": {
        "unique": false
      }
    }
  }
}
EOF

指定された値が有効な場合、このエンドポイントへの応答コードは 201 Created になり、作成されたマッピングの完全な詳細が応答のペイロードに含まれます。この応答ペイロードの出力は、マッピングの詳細​エンドポイントと同じになります。

入力にエラーがあった場合、応答コードは 400 Bad Request になり、エラーに関する詳細が応答の JSON ペイロードに含まれます。

マッピングを編集する

既存のマッピングを個別に編集できます。

PUT /mappings/<mapping_id>

ペイロードは、マッピングの作成時に送信するものとほぼ同じです。違いは revision​ 属性の存在です。既存のマッピングには、そのマッピングの詳細に API で取得​できる revision​ 属性があります。

revision​ 値は変更せずに​ PUT マッピングの編集リクエストで送り返す必要があります。この値によって、マッピングを送り返す機会を得る前に他の誰かによってマッピングが更新されていないことを API で確認できます。理想的なワークフローは、マッピングの詳細を取得し、config​ 属性を抽出し、適切な変更を加えてから、同じ URL に再び PUT するというものです。

成功応答は 200 OK で、マッピング全体のペイロードが含まれます。

作成エンドポイントと同様に、ほとんどのエラーは 400 Bad Request を返し、詳細は応答ペイロードに含まれます。送り返された revision​ が、マッピングの現在のものと一致しない場合、409 Conflict が返されます。この 409 により、複数のユーザーまたはプロセスが、矛盾した方法で同じマッピングを変更することを防ぎます。

マッピングを削除する

マッピングを個別に削除できます。

DELETE /mappings/<mapping_id>

$ curl -X DELETE https://connect-3-virginia.heroku.com/api/v3/mappings/7b5a2105-9845-43cd-9648-9406ee745bf5 \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

このエンドポイントは、マッピングが削除されたことを示す 204 No Content を返します。この応答が返された後、データベースからのデータの削除など、追加のタスクが引き続き実行される場合があります。

マッピングをリロードする

PostgreSQL データベース内のテーブルが Salesforce と同期しなくなった場合、API を使用して Postgres テーブルをクリアし、Salesforce から最新のデータを取得することができます。

POST /mappings/<mapping_id>/actions/reload

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/mappings/7b5a2105-9845-43cd-9648-9406ee745bf5/actions/reload \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

正常な応答には、202 HTTP ステータスコードが表示されます。現在の状態をチェックするには、マッピングの詳細を取得​してください。

マッピングを中止する

マッピングを中止すると、そのマッピングで実行中のすべての操作がキャンセルされ、他のアクションを実行できるようになります。マッピングを中止すると、操作の実行が予想よりも長引いている場合や、操作を誤って開始した場合に役立つことがあります。

POST /mappings/<mapping_id>/actions/abort

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/mappings/7b5a2105-9845-43cd-9648-9406ee745bf5/actions/abort \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

正常な応答には、202 HTTP ステータスコードが表示されます。一部の操作を中止すると、次のポーリングで正常な同期が行われます。その他の操作では、同期を再開するには、中止後にマッピングのリロード​が必要です。リロードが必要な状況については、「States and Aborted Mapping Operations​」(状態および中止されたマッピング操作) を参照してください。現在の状態をチェックするには、マッピングの詳細を取得​してください。

互換性ポリシー

Heroku Connect API は常に開発中であり、時間と共に変更が加えられます。新しいエンドポイント、新しい入力、または新しいペイロードの内容などの一部の変更は、既存の動作に影響しません。これらの変更は、いつでも導入される可能性があります。既存の動作を変更または削除するその他の変更には、既存のアプリケーションとの互換性を確保するための以下のポリシーがあります。

安定状態のエンドポイントに関しては、互換性に影響する変更が予定されている場合、Heroku は遅くともその変更の実施の 30 日前までにすべてのユーザーに通知します。この通知には、変更の性質、背景にある理由、および古い動作から新しい動作に移行するために必要な手順が含まれています。またこのドキュメントには、これらの詳細が 30 日間記載されます。30 日が経過すると、新しい動作が現行のものになり、古い動作はこのドキュメントから削除されます。

特に明記されていない場合、ドキュメントが公開されているすべての API エンドポイントは安定状態です。このドキュメントでは、実験的なエンドポイントまたは動作が明確に示されています。実験的な機能は API の利用者からフィードバックを得る目的で提供されており、予告なしにいつでも変更される可能性があります。

新しいバージョンはリリースされる前に、既存のバージョンを代替する準備ができるまでの間、実験的な機能として利用可能になります。その時点で、ルートエンドポイント​が更新されます。Heroku は、互換性ポリシー​での説明と同様に、古いバージョンが削除される 30 日前にこの変更について通知します。