投票卡片

GET accounts/:account_id/cards/poll

检索与当前账号关联的部分或所有投票卡片详细信息。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/poll

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_ids
可选

通过指定以逗号分隔的标识符列表,将响应范围限定至所需的投票卡片。最多可提供 200 个 ID。

类型:string

示例:57i77

count
可选

指定每个不同请求尝试检索的记录数量。

类型:int

默认值:200
最小值、最大值:11000
cursor
可选

指定光标以获取下一页结果。参阅分页了解更多信息。

类型:string

示例:8x7v00oow

q
可选

可选查询,按 name 指定卡片范围。省略此参数可检索所有卡片。最大长度:80 个字符。

注意:执行不区分大小写的前缀匹配。

类型:string

示例:night

sort_by
可选

根据支持的属性,按升序或降序排序。参阅排序了解更多信息。

类型:string

示例:created_at-asc

with_deleted
可选

在请求中包含已删除的结果。

类型:boolean

默认值:false
可能值:truefalse
with_total_count
可选

包含 total_count 响应属性。

注意:不包含此参数和 cursor

注意:包含 total_count 的请求速率限制较低,目前设置为每 15 分钟 200 次。

类型:boolean

默认值:false
可能值:truefalse

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/poll?card_ids=57i77

响应示例

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "best coast poll",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "East",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "West",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

GET accounts/:account_id/cards/poll/:card_id

检索与当前账号关联的特定投票卡片。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/poll/:card_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_id
必需

请求中对正在操作的投票卡片的引用。

类型:string

示例:57i8t

with_deleted
可选

在请求中包含已删除的结果。

类型:boolean

默认值:false
可能值:truefalse

请求示例

GET https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/poll/57i8t

响应示例

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "text only poll",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Morning",
    "second_choice": "Evening",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

POST accounts/:account_id/cards/poll

创建与指定账号关联的新投票卡片。此端点支持使用图像、视频或无需媒体创建投票卡片。使用媒体的投票称为 Media Forward Poll。

注意:Media Forward Poll 产品正在测试中,并且需要 PROMOTED_MEDIA_POLLS 账号功能。

注意:无法更新 (PUT) 投票卡片。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/poll

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

duration_in_minutes
必需

投票保持开放的时间(单位:分钟)。指定 duration_in_minutes 后,投票将关闭,并且将不再接受投票。此参数与响应中的 end_time 一致。

注意:此参数在卡片创建完成且尚未添加至推文中时即开始计时。

类型:int

最小值、最大值:510080

first_choice
必需

第一个投票选项。最大长度:25 个字符。

类型:string

示例:One

name
必需

卡片名称。

类型:string

示例:poll card

second_choice
必需

第二个投票选项。最大长度:25 个字符。

类型:string

示例:Two

fourth_choice
可选

第四个投票选项。最大长度:25 个字符。

注意:使用此参数时,必须设置第一、第二和第三个选项。

类型:string

示例:Four

media_key
可选

将在此卡片中使用的媒体库图像或视频 media_key

此字段为只写字段。在响应中,API 将为此媒体提供 Twitter URL。

注意:图像或视频必须位于账号的媒体库。

注意:图像最小宽度必须为 800 像素,且宽高比为 1.91:1(宽:高)。

third_choice
可选

第三个投票选项。最大长度:25 个字符。

注意:使用此参数时,必须设置第一和第二个选项。

类型:string

示例:Three

请求示例

POST https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll

响应示例

{
  "request": {
    "params": {
      "first_choice": "East",
      "name": "best coast poll",
      "second_choice": "West",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "best coast poll",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "East",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "West",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

DELETE accounts/:account_id/cards/poll/:card_id

永久删除属于当前账号的指定投票卡片。

注意:此操作为硬删除。删除后,将无法恢复删除的卡片。

资源 URL

https://ads-api.twitter.com/10/accounts/:account_id/cards/poll/:card_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中,通常是所有广告商 API 请求的必要参数,不包含 GET accounts。指定账号必须与已验证的用户关联。

类型:string

示例:18ce54d4x5t

card_id
必需

请求中对正在操作的投票卡片的引用。

类型:string

示例:57i9t

请求示例

DELETE https://ads-api.twitter.com/10/accounts/18ce54d4x5t/cards/poll/57i9t

响应示例

{
  "data": {
    "name": "poll with image",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll",
      "account_id": "18ce54d4x5t"
    }
  }
}