ユーザ管理

ユーザー管理エンドポイントリファレンス

Marketo User Management エンドポイントは、ユーザーレコードに対してCRUD操作を実行します。 ユーザーを作成するには、招待状を送信します。 その後、ユーザーはパスワードを設定し、初めてMarketoにアクセスします。

User Management API を使用する際、他の Marketo REST API とは次の点が異なります。

  • HTTP ヘッダーにアクセストークンを送信します。 アクセストークンをクエリ文字列パラメーターとして渡すことはできません。 認証ガイド ​を参照してください。

  • REST API ​ カスタムサービス ​のユーザーロールを作成する際に、次の各グループから権限を選択します。

    1. 管理にアクセスグループの「ユーザにアクセス」権限
    2. Access API グループの「User Management API にアクセス」
  • 応答本文に「success」ブール属性が含まれていないため、HTTP応答ステータスコードを評価します。 呼び出しが成功すると、ステータスコード 200が返されます。 失敗した呼び出しは、200以外のステータスコードと、エラーコードと説明メッセージを含む標準の「errors」配列を返します。

  • 日時の文字列をyyyyMMdd'T'HH:mm:ss.SSS't'+|-hhmmとして書式設定します。 この形式は、createdAt、updatedAt、expiresAtに適用されます。

  • User Management API エンドポイントのプレフィックスに「/rest」を付けないでください。

クエリ

ユーザー管理クエリは、すべてのユーザー、役割、ワークスペースを取得できます。 また、1人のユーザー、またはユーザーID別に関連する役割とワークスペースレコードを取得することもできます。

ID 別のユーザー

ID によるユーザーの取得エンドポイントは、単一の userid パスパラメーターを受け取り、招待を受け入れたユーザーの単一のユーザーレコードを返します。

GET /userservice/management/v1/users/{userid}/user.json
{
  "userid": "jamie@houselannister.com",
  "firstName": "Jamie",
  "lastName": "Lannister",
  "emailAddress": "jamie@lannister.com",
  "optedIn": false,
  "failedLogins": 0,
  "failedDeviceCode": 0,
  "isLocked": false,
  "lockedReason": null,
  "id": 0,
  "apiOnly": false,
  "userRoleWorkspaces": [
    {
      "accessRoleId": 1,
      "accessRoleName": "Admin",
      "workspaceId": 0,
      "workspaceName": "AllZones"
    },
    {
      "accessRoleId": 2,
      "accessRoleName":
      "Standard User",
      "workspaceId": 1008,
      "workspaceName": "World"
    }
  ],
  "expiresAt": "2020-12-31T08:00:00.000t+0000",
  "lastLoginAt": "2020-02-05T01:02:23.000t+0000"
}

ID で指定された招待ユーザー

ID により招待されたユーザーの取得エンドポイントは、単一の userid パスパラメーターを受け取り、「保留中」のユーザー(まだ招待を受け入れていないユーザー)の単一のユーザーレコードを返します。

GET /userservice/management/v1/users/{userid}/invite.json
{
    "id": 25112,
    "firstName": "Jamie",
    "lastName": "Lannister",
    "emailAddress": "jamie@lannister.com",
    "userId": "jamie@lannister.com",
    "subscriptionId": 3381,
    "status": "pending",
    "expiresAt": "20200807T20:49:54.0t+0000",
    "createdAt": "20200731T20:49:54.0t+0000",
    "updatedAt": "20200731T20:49:54.0t+0000"
}

ID で指定されたロールとワークスペース

Id🔗による役割とワークスペースの取得エンドポイントは、1つのuserid パスパラメーターを取り、ユーザーの役割とワークスペースレコードを返します。 応答配列内の各オブジェクトには、役割とワークスペース IDおよび名前が含まれます。

GET /userservice/management/v1/users/{userid}/roles.json
[
  {
    "accessRoleId": 1,
    "accessRoleName": "Admin",
    "workspaceId": 0,
    "workspaceName": "AllZones"
  },
  {
    "accessRoleId": 2,
    "accessRoleName": "Standard User",
    "workspaceId": 1008,
    "workspaceName": "World"
  }
]

ユーザの参照

Get Users エンドポイントは、すべてのユーザーレコードを返します。 次のオプションの整数パラメーターをサポートしています。

  • pageSizeは、返すエントリの最大数を指定します。 デフォルトは20、最大は200です。
  • pageOffsetは、エントリの取得を開始する場所を指定します。 デフォルトは0で、pageSizeと一緒に使用できます。
GET /userservice/management/v1/users/allusers.json
[
  {
    "userid": "jamie@lannister.com",
    "firstName": "Jamie",
    "lastName": "Lannister",
    "emailAddress": "jamie@houselannister.com",
    "id": 6785,
    "apiOnly": false
  },
  {
    "userid": "jeoffery@housebaratheon.com",
    "firstName": "Jeoffery",
    "lastName": "Baratheon",
    "emailAddress": "jeoffery@housebaratheon.com",
    "id": 7718,
    "apiOnly": false
  },
  {
    "userid": "rickon@housestark.com",
    "firstName": "Rickon",
    "lastName": "Stark",
    "emailAddress": "rickon@housestark.com",
    "id": 8612,
    "apiOnly": false
  }
]
NOTE
上記のコードサンプルでは、表示されるuserid は、Adobe IMS に移行されたお客様の ID です。 まだ移行していないお客様には、userid フィールドに通常のメールアドレスが表示されます。

ロールの参照

ロールを取得エンドポイントは、すべてのロールレコードのリストを返します。

GET /userservice/management/v1/users/roles.json
[
    {
        "id": 1,
        "name": "Admin",
        "description": "All permissions",
        "type": "system",
        "hidden": false,
        "onlyAllZones": true,
        "createdAt": "20100327T18:27:42.0t+0000",
        "updatedAt": "20100327T18:27:42.0t+0000"
    },
    {
        "id": 2,
        "name": "Standard User",
        "description": "All permissions except Admin",
        "type": "system",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20100327T18:27:42.0t+0000",
        "updatedAt": "20180423T02:33:29.0t+0000"
    },
    {
        "id": 24,
        "name": "RTP Launcher",
        "description": "Role required for launcher in RTP",
        "type": "system",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20151024T01:45:40.0t+0000",
        "updatedAt": "20171024T23:41:24.0t+0000"
    },
    {
        "id": 25,
        "name": "RTP Editor",
        "description": "Role required for editor in RTP",
        "type": "system",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20151024T01:45:40.0t+0000",
        "updatedAt": "20171024T23:41:24.0t+0000"
    },
    {
        "id": 101,
        "name": "Analytics User",
        "description": "Has access to Analytics",
        "type": "custom",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20100327T18:27:42.0t+0000",
        "updatedAt": "20180423T02:33:29.0t+0000"
    },
    {
        "id": 102,
        "name": "Marketing User",
        "description": "All permissions except Admin",
        "type": "custom",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20100327T18:27:42.0t+0000",
        "updatedAt": "20100327T18:27:42.0t+0000"
    },
    {
        "id": 103,
        "name": "Web Designer",
        "description": "Has access to Design Studio except approval permission",
        "type": "custom",
        "hidden": false,
        "onlyAllZones": false,
        "createdAt": "20100327T18:27:42.0t+0000",
        "updatedAt": "20180423T02:33:29.0t+0000"
    }
]

ワークスペースの参照

ワークスペースを取得エンドポイントは、すべてのワークスペースレコードのリストを返します。

GET /userservice/management/v1/users/workspaces.json
[
  {
    "id": 1,
    "name": "Default",
    "description": "Initial workspace for Marketing Activities, Design Studio, and so on.",
    "globalViz": 0,
    "status": "active",
    "currencyInfo": null,
    "createdAt": "20160910T23:08:05.0t+0000",
    "updatedAt": "20160910T23:08:05.0t+0000"
  },
  {
    "id": 1008,
    "name": "World",
    "description": "",
    "globalViz": 0,
    "status": "active",
    "currencyInfo": null,
    "createdAt": "20181119T21:59:36.0t+0000",
    "updatedAt": "20181119T21:59:36.0t+0000"
  },
  {
    "id": 1009,
    "name": "Reproduction - US English - All Leads",
    "description": "A Workspace for recreating customer-reported problems.",
    "globalViz": 1,
    "status": "active",
    "currencyInfo": null,
    "createdAt": "20190129T23:36:37.0t+0000",
    "updatedAt": "20190129T23:36:37.0t+0000"
  },
  {
    "id": 1010,
    "name": "US",
    "description": "United States - Qualified Leads",
    "globalViz": 0,
    "status": "active",
    "currencyInfo": null,
    "createdAt": "20190322T15:55:40.0t+0000",
    "updatedAt": "20190322T15:55:40.0t+0000"
  }
]

ユーザの招待

Adobe IMS 統合サブスクリプションでは、このエンドポイントは API 専用ユーザの招待のみをサポートします。 標準ユーザーを招待するには、代わりに Adobe User Management API を使用します。

Invite User エンドポイントは、新しいユーザーに「Welcome to Marketo」のメール招待状を送信します。 このメールには、「Marketoにログイン」リンクが含まれています。 受信者はリンクを選択し、パスワードを作成してMarketoにアクセスできます。

受信者が招待を受け入れるまで、そのステータスは「保留中」であり、ユーザーレコードを編集することはできません。 保留中の招待状は、送信されてから7日後に有効期限が切れます。 詳しくは、Marketo ユーザー管理ドキュメント ​を参照してください。

リクエスト本文にパラメーターをapplication/json形式で渡します。

必要なパラメーターはemailAddress、firstName、lastName、およびuserRoleWorkspacesです。 userRoleWorkspaces パラメーターは、accessRoleIdおよびworkspaceId属性を含むオブジェクトの配列です。

userid パラメーターは、ログインに使用される一意のユーザーIDであり、電子メールアドレスとしてフォーマットする必要があります。 リクエストがuseridを省略した場合、その値はデフォルトでemailAddressの値になります。

ブール値の apiOnly パラメーターは、ユーザーが API 専用ユーザーであるかどうかを指定します。 expiresAt パラメーターは、ユーザーログインの有効期限を指定し、ミリ秒単位でW3C ISO-8601形式を使用します。 リクエストがexpiresAtを省略した場合、ユーザーは期限切れになりません。 reason パラメーターは、招待の理由を説明します。

招待が成功すると、エンドポイントは「true」を返します。 それ以外の場合は、エラーメッセージが返されます。

POST /userservice/management/v1/users/invite.json
Content-Type: application/json
{
  "emailAddress": "daenerys@housetargaryen.com",
  "firstName": "Daenerys",
  "lastName": "Targaryen",
  "expiresAt": "2020-12-31T23:59:59-05:00",
  "reason": "Keeper of dragons",
  "userRoleWorkspaces": [
    {
      "accessRoleId": 1,
      "workspaceId": 0
    }
  ]
}
true

次の図は、新規ユーザーに送信された「Marketoへようこそ」電子メールを示しています。 件名は「Marketo Login Information」です。 送信者は、REST API カスタムサービス ​に関連付けられたAPI専用ユーザーの電子メールアドレスです。 firstName、lastName、emailAddressの各パラメーターで受信者を指定します。

ユーザー招待メール

ユーザーは、パスワードを2回入力し、「パスワードを作成」ボタンを選択して、招待を受け入れます。 その後、利用者はMarketoへのアクセス権を取得します。

ユーザーの更新

ユーザーが招待を受け入れた後、ユーザー属性を更新したり、ユーザーを削除したりできます。 属性をリクエスト本文のパラメーターとしてapplication/json形式で渡します。

ユーザ属性の更新

Adobe IMS 統合サブスクリプションでは、このエンドポイントは API 専用ユーザの属性の更新のみをサポートします。 標準ユーザーの属性を更新するには、代わりに Adobe User Management API を使用します。

ユーザー属性を更新エンドポイントは、単一の userid パスパラメーターを受け取り、単一のユーザーレコードを返します。 リクエスト本文には、更新する 1 つ以上のユーザー属性(emailAddress、firstName、lastName、expiresAt)が含まれます。

POST /userservice/management/v1/users/{userid}/update.json
Content-Type: application/json
{
  "firstName": "JAMIE",
  "lastName": "LANISTER",
  "expiresAt": "20211231T08:00:00.000t+0000"
}
{
  "userid": "jamie@houselannister.com",
  "firstName": "JAMIE",
  "lastName": "LANISTER",
  "emailAddress": "jamie@houselannister.com",
  "optedIn": false,
  "failedLogins": 0,
  "failedDeviceCode": 0,
  "isLocked": false,
  "lockedReason": null,
  "id": 0,
  "apiOnly": false,
  "userRoleWorkspaces": [
    {
      "accessRoleId": 1,
      "accessRoleName": "Admin",
      "workspaceId": 0,
      "workspaceName": "AllZones"
    },
    {
      "accessRoleId": 2,
      "accessRoleName":
      "Standard User",
      "workspaceId": 1008,
      "workspaceName": "World"
    }
  ],
  "expiresAt": "2021-12-31T08:00:00.000t+0000"
  "lastLoginAt": "2020-02-05T01:02:23.000t+0000"
}

ユーザの削除

Adobe IMS 統合サブスクリプションでは、このエンドポイントは API 専用ユーザの削除のみをサポートします。 標準ユーザーを削除するには、代わりに Adobe User Management API を使用します。

ユーザーを削除エンドポイントは、単一の userid パスパラメーターを受け取り、インスタンスから対応するユーザーを削除します。 これは、破壊的な削除であり、元に戻すことはできません。 成功した場合は 200 ステータスコードが返され、それ以外の場合はエラーメッセージが返されます。

POST /userservice/management/v1/users/{userid}/delete.json

招待されたユーザの削除

招待されたユーザーを削除エンドポイントは、単一の userid パスパラメーターを受け取り、対応する「保留中」のユーザー(まだ招待を受け入れていないユーザー)をインスタンスから削除します。 これは、破壊的な削除であり、元に戻すことはできません。 成功した場合は 200 ステータスコードが返され、それ以外の場合はエラーメッセージが返されます。

POST /userservice/management/v1/users/{userid}/invite/delete.json

ロールの更新

役割は追加または削除できます。 属性をリクエスト本文のパラメーターとしてapplication/json形式で渡します。

ロールの追加

ロールを追加エンドポイントは、単一の userid パスパラメーターを受け取り、対応するユーザーに 1 つ以上のユーザーロールを追加します。 リクエスト本文には、それぞれ accessRoleId 属性と workspaceId 属性を含む 1 つ以上のオブジェクトのリストが含まれます。 成功した場合、指定したユーザーの accessRoleId/workspaceId ペアのリスト全体が返されます。

POST /userservice/management/v1/users/{userid}/roles/create.json
Content-Type: application/json
[
  {
    "accessRoleId": 2,
    "workspaceId": 1008
  }
]
[
  {
    "accessRoleId": 1,
    "accessRoleName": "Admin",
    "workspaceId": 0,
    "workspaceName": "AllZones"
  },
  {
    "accessRoleId": 2,
    "accessRoleName": "Standard User",
    "workspaceId": 1008,
    "workspaceName": "World"
  }
]

ロールの削除

ロールを削除エンドポイントは、単一の userid パスパラメーターを受け取り、対応するユーザーから 1 つ以上のユーザーロールを削除します。 リクエスト本文には、それぞれ accessRoleId 属性と workspaceId 属性を含む 1 つ以上のオブジェクトのリストが含まれます。 成功した場合、指定したユーザーの accessRoleId/workspaceId ペアの残りのリストが返されます。

POST /userservice/management/v1/users/{userid}/roles/delete.json
Content-Type: application/json
[
  {
    "accessRoleId": 2,
    "workspaceId": 1008
  }
]
[
  {
    "accessRoleId": 1,
    "accessRoleName": "Admin",
    "workspaceId": 0,
    "workspaceName": "AllZones"
  }
]
recommendation-more-help
marketo-developer-help