ข้อมูลรายงานการค้นหา

เมธอด reportData.query เป็นวิธีแบบซิงโครนัส ในการดึงข้อมูลรายงาน ซึ่งแตกต่างจากบริการ Reports มาตรฐานที่สร้างรายงานแบบไฟล์ (CSV หรือ Excel) โดยเมธอดนี้จะแสดงผลข้อมูล JSON ที่มีโครงสร้างในคำตอบโดยตรง จึงไม่จำเป็นต้องกำหนด สร้าง และบันทึกทรัพยากร Report ไว้ล่วงหน้า ทำให้เหมาะสำหรับการดึงข้อมูลและการสำรวจข้อมูลแบบเรียลไทม์

ภาพรวม

อ่านคำแนะนำนี้เพื่อทำความคุ้นเคยกับการใช้ปลายทางนี้เพื่อค้นหาข้อมูลการรายงานของ Campaign Manager 360

เตรียมคำขอ

สร้าง ReportDataQueryRequest โดยระบุเมตริก มิติข้อมูล ช่วงวันที่ ตัวกรอง และเกณฑ์การจัดเรียง

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

ออบเจ็กต์ DateRange ที่ระบุช่วงเวลาสำหรับการ ค้นหา ซึ่งอาจเป็นช่วงวันที่ที่กำหนดเองหรือช่วงวันที่สัมพัทธ์

dimensionNames

รายการชื่อมิติข้อมูลมาตรฐานที่จะจัดกลุ่มตาม

metricNames

ต้องระบุ รายการชื่อเมตริกมาตรฐานที่จะรวม

dimensionFilters

รายการออบเจ็กต์ DimensionValue ที่ใช้กรอง ข้อมูลรายงาน ใช้ตัวกรองนี้เพื่อจำกัดผลการค้นหาให้แสดงเฉพาะค่าที่ต้องการของมิติข้อมูล

sortBys

การกำหนดค่าการจัดเรียงสำหรับมิติข้อมูลหรือเมตริก การกำหนดค่าแต่ละรายการจะมีชื่อฟิลด์และลำดับการจัดเรียง

maxResults

จำนวนแถวสูงสุดที่จะแสดงผลต่อหน้า (ค่าเริ่มต้น: 100, สูงสุด: 1000)

การใส่เลขหน้า

ฟิลด์ maxResults จะควบคุมจำนวนผลลัพธ์ที่แสดงผลในการตอบกลับครั้งเดียว เช่น หากคุณตั้งค่า maxResults เป็น 10 API จะแสดงผลลัพธ์ไม่เกิน 10 รายการ API อาจแสดงผลลัพธ์น้อยกว่า 10 รายการหากมีผลลัพธ์ที่ตรงกับคำขอของคุณน้อยกว่า 10 รายการ

หากมีผลลัพธ์เพิ่มเติม การตอบกลับจะมี nextPageToken หากต้องการดึงผลลัพธ์หน้าถัดไป ให้ส่งคำขอเดิมอีกครั้งโดยตั้งค่าฟิลด์ pageToken เป็นโทเค็นนี้ และเก็บพารามิเตอร์คำขออื่นๆ ไว้เหมือนเดิม

ส่งคำขอ

ส่งคำขอ HTTP POST ไปยังreportdata/query ปลายทางดังนี้

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

ตรวจสอบว่าคำขอของคุณได้รับการตรวจสอบสิทธิ์ด้วยข้อมูลเข้าสู่ระบบ OAuth 2.0 มาตรฐานและขอบเขตที่จำเป็น ดูข้อมูลเพิ่มเติมได้ที่ให้สิทธิ์คำขอสำหรับ ข้อมูล

การตอบกลับที่สำเร็จ

การค้นหาที่สำเร็จจะแสดงผลการตอบกลับ HTTP 200 OK พร้อมเพย์โหลด JSON ที่มี columnHeaders, rows และ totalRow

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

ชื่อและประเภท (DIMENSION หรือ METRIC) ของฟิลด์ที่แสดงผล

rows

รายการออบเจ็กต์ ReportDataRow ที่มี ผลการค้นหา ค่าสตริงในแต่ละแถวจะตรงกับ columnHeaders ตามตำแหน่ง

totalRow

แถวรวมแถวเดียวที่แสดงผลรวมของเมตริกที่ตรงกันทั้งหมด ฟิลด์มิติข้อมูลและเมตริกที่รวมไม่ได้ (เช่น เมตริกการเข้าถึง เช่น uniqueReachTotalReach) จะว่าง ("") ในแถวนี้

nextPageToken

โทเค็นที่ใช้ในคำขอที่ตามมาเพื่อดึงข้อมูลหน้าถัดไปหากมีแถวเพิ่มเติม

เวลาในการตอบสนองและระยะหมดเวลา

เนื่องจากเป็นปลายทางแบบซิงโครนัส การค้นหาจะดำเนินการทันทีและระบบจะแสดงผลข้อมูลในการตอบกลับโดยตรง (สูงสุดตามขีดจำกัดการใส่เลขหน้า maxResults) การค้นหามีเวลาดำเนินการสูงสุด 60 วินาที หากการค้นหาเกินขีดจำกัดนี้ API จะยกเลิกการดำเนินการและแสดงข้อผิดพลาด HTTP 503 Service Unavailable

หากพบข้อผิดพลาดนี้ ให้ลองจำกัดช่วงวันที่ให้แคบลง จำกัดตัวกรองให้แคบลง (เช่น กรองตามผู้ลงโฆษณาหรือแคมเปญที่เฉพาะเจาะจง) หรือลดจำนวนมิติข้อมูลและเมตริกที่ขอ หรือเรียกใช้ Report โดยใช้ reports.run เพื่อสร้างไฟล์รายงานที่ดาวน์โหลดได้แบบไม่พร้อมกัน

ขีดจำกัดและข้อจำกัดของการค้นหา

ปลายทาง reportdata.query มีขีดจำกัดหลายอย่าง เพื่อให้มั่นใจว่าการตอบกลับจะเชื่อถือได้ ระบบจะปฏิเสธคำขอที่ละเมิดข้อจำกัดเหล่านี้ด้วยการตอบกลับ HTTP 400 Bad Request

ขีดจำกัดช่วงวันที่

• สำหรับช่วงวันที่ที่กำหนดเอง startDate ต้องอยู่ในช่วงเวลาที่ข้อมูลพร้อมใช้งานสำหรับประเภทข้อมูลรายงานที่ขอ ดูรายละเอียดได้ที่ ความพร้อมใช้งานของข้อมูล

ข้อจำกัดของเมตริกและมิติข้อมูล

• ต้องระบุเมตริกอย่างน้อย 1 รายการใน metricNames
• เมตริกและมิติข้อมูลในรายการ metricNames และ dimensionNames ต้องไม่ซ้ำกัน
• คุณไม่สามารถใช้เมตริกและมิติข้อมูลที่มีป้ายกำกับว่า ดาวน์โหลดเท่านั้น ใน การค้นหาเหล่านี้

ขีดจำกัดโควต้า

คำขอที่ส่งไปยังปลายทางนี้จะใช้โควต้าต่อไปนี้

• ขีดจำกัดอัตราการส่งคำขอของผู้ใช้: 120 คำขอต่อนาทีต่อผู้ใช้ (2 QPS)
• ขีดจำกัดรายวันต่อโปรเจ็กต์: 10,000 คำขอต่อวันต่อโปรเจ็กต์

คำขอที่เกินขีดจำกัดเหล่านี้จะล้มเหลวและแสดงข้อผิดพลาด HTTP 429 Too Many Requests หากคุณเลื่อนดูผลลัพธ์ คำขอแต่ละรายการสำหรับหน้าใหม่ (โดยใช้พารามิเตอร์ pageToken) จะนับเป็นการค้นหาแยกต่างหากและใช้โควต้านี้