API 要求を使用する

学習の目的

この単元を完了すると、次のことができるようになります。

Pardot API に対するコールのしくみを説明する。
API 要求の基本を説明する。

Pardot API を使用する

このモジュールでは、受講者が Apex と開発者コンソールに関する基本的な知識を有していることを前提としています。

Pardot API を使用すると、Pardot 内のデータにアプリケーションからアクセスできます。データにアクセスしようとする試みは、コールまたは要求と呼ばれます。要求を介して、Pardot オブジェクトで次のような複数の一般的な操作を実行できます。

create: 指定されたパラメーターを使用して、オブジェクトのインスタンスを作成します。
read: 指定されたオブジェクトに関する情報を取得します。
query: 指定されたオブジェクトに関する情報を取得します。
update: 既存のオブジェクトの要素を更新します。
upsert: 既存のオブジェクトが存在する場合、その要素を更新します。オブジェクトが存在しない場合は、指定されたパラメーターを使用してオブジェクトが作成されます。

メモ: この単元の例は、Pardot API の v3 および v4 に基づいています。バージョン 5 では動作が若干異なりますので、v5 を使用している場合は、Pardot 開発者向けドキュメントを確認してください。

Pardot API に要求を送信する方法は多数ありますが、ここではすべては取り上げません。この単元では、基本を理解できるようにシンプルな HTTP での要求を紹介します。

使用する言語や方法にかかわらず、API に対するすべての要求では、次のことが必須となります。

HTTP GET または POST のいずれかを使用する。バージョン 5 では、PATCH および DELETE 要求もサポートされている。
HTTP 認証ヘッダーでアクセストークンを渡す。
HTTP Pardot-Business-Unit-Id ヘッダーで Pardot ビジネスユニット ID を渡す。
Pardot 環境に適した URL を使用する。

「Pardot API 用の Salesforce OAuth」で説明したように、Pardot API 要求を発行する前には、Salesforce OAuth エンドポイントを使用して認証する必要があります。

紹介する例を Pardot アカウントで実行する場合は、Sandbox の使用をお勧めします。このモジュールの一部のタスクを実行すると、アカウントのデータが変更される場合があります。

このモジュールでは、受講者が Pardot 開発者であり、API の認証とコールを行うための適切な権限を有しているものと想定しています。ただし、Pardot 開発者でなくても問題ありません。このまま読み進み、本番組織で開発者が手順をどのように実行するのかを学習しましょう。Trailhead Playground で次の手順を実行しないでください。Trailhead Playground では Pardot を使用できません。

GET 要求を実行する

GET 要求では、query 操作と read 操作を使用して Pardot からデータを取得できますビジネスユニットのすべてのカスタム項目を一覧表示するシンプルな GET 要求を見てみましょう。

GET https://pi.pardot.com/api/customField/version/4/do/query?format=json HTTP/1.1
Host: pi.pardot.com
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>

要求を分解して、各部分を確認しましょう。まずは Uniform Resource Identifier (URI) から始めます。GET https://<ENVIRONMENT_URL>/api/<OBJECT>/version/<API_VERSION>/do/<OPERATION>?format=<FORMAT>

環境 URL: この例では pi.pardot.com を使用していますが、環境種別に応じた URL を使用できます。デモ、開発者組織、Sandbox の各環境は、pi.demo.pardot.com というドメインでホストされています。トレーニング環境と本番環境は、pi.pardot.com というドメインでホストされています。
オブジェクト: データの要求先のオブジェクトです。この例では、CustomField オブジェクトをクエリしています。
API バージョン: 使用している API のバージョンです。ここでは、v4 を使用しています。
操作: 実行している操作です。ここでは、query を使用しています。
形式: 出力形式です。XML または JSON のいずれかになります。ここでは、json を使用しています。

URI の説明が終わったところで、コールのヘッダー行を詳しく見てみましょう。

'Authorization:Bearer <ACCESS TOKEN>': ユーザーが認証され、データにアクセスする権限を持っていることを Pardot に通知します。
'Pardot-Business-Unit-Id:<BUSINESS UNIT ID>': データの取得元になるビジネスユニットを Pardot に通知します。
Host: Pardot 環境の URL です。

このコールでは、ビジネスユニットのカスタム項目とそのメタデータが返されます。

{
   "@attributes" : {
     "version" : 1,
     "stat" : "ok"
   },
   "result" : {
     "customField" : [
        {
          "id" : 14141,
          "is_use_values" : false,
          "crm_id" : null,
          "is_record_multiple_responses" : false,
          "field_id" : "Attended_Event",
          "type_id" : 1,
          "updated_at" : "2020-08-04 05:45:36",
          "is_analytics_synced" : false,
          "type" : "Text",
          "created_at" : "2020-08-04 05:45:36",
          "name" : "Attended Event?"
          },
        ],
        "total_results" : 1
      }
}

各オブジェクトの項目に関する詳細は、「Object Field Reference (オブジェクト項目リファレンス)」ドキュメントを参照してください。

POST 要求を実行する

POST 要求では、Pardot データを追加または変更する操作を使用できます。以下の例では、POST 要求を使用して、「Spring Leads (春のリード)」というリストを作成しています。

POST /api/list/version/4/do/create?format=json HTTP/1.1
Host: pi.pardot.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>
name=Spring Leads Nurture&title=Spring Leads title&description=A list to nurture spring leads

この要求を分解してみましょう。GET の例では、URI、認証、ビジネスユニットの各ヘッダーを確認しました。ここでは他のコンポーネントについて説明します。

Content-Type:application/x-www-form-urlencoded: 要求に含まれるデータの種別をサーバーに通知します。バージョン 5 の API でサポートされる種別は JSON のみです。
name=Spring Leads Nurture: リストの内部名を「Spring Leads Nurture (春のリードのナーチャリング)」に設定します。
title=Spring Leads: リストに「Spring Leads (春のリード)」というタイトルを付けます。
description=A list to nurture spring leads: リストにテキストの説明を追加します。

この要求をサーバーに送信すると、指定した条件でリストが作成され、Pardot から応答が返されます。応答は次のようになります。

{
   "@attributes": {
      "stat": "ok",
      "version": 1
   },
   "list": {
        "id": 1000,
        "name": "Spring Leads Nurture",
        "is_public": false,
        "is_dynamic": false,
        "title": "Spring Leads",
        "description": "A list to nurture spring leads",
        "is_crm_visible": false,
        "created_at": "2021-02-12 08:09:10",
        "updated_at": "2021-02-12 08:09:10"
    }
}

応答には、作成したリストとそのメタデータが含まれています。

この例をさらに一歩進めて、POST 要求を使用して新しいリストにプロスペクトを追加してみましょう。オブジェクトの既存のインスタンス、つまり新しいリストを更新するので、update メソッドを使用します。

このタスクを完了すると、Pardot のデータが変更されますので、続行するには注意が必要です。

まず、プロスペクトを追加するリストのリスト ID をコピーします。次に、リストに追加するプロスペクトの ID を見つけます。ID は、プロスペクトオブジェクトで query 操作を使用すると取得できます。

リスト ID: 1000
プロスペクト ID: XXXXX

POST /api/prospect/version/4/do/update/id/XXXXX?format=json HTTP/1.1
Host: pi.pardot.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <ACCESS TOKEN>
Pardot-Business-Unit-Id: <BUSINESS UNIT ID>
list_<ID>=1000

これで、Pardot API にコールを実行するための基本を理解できたので、独自のインテグレーションに取り掛かることができます。次の単元では、APEX を使用して要求を実行する例を紹介します。

API 要求を使用する

学習の目的

Pardot API を使用する

GET 要求を実行する

POST 要求を実行する

リソース