Metadata API - คู่มือนักพัฒนาซอฟต์แวร์

เอกสารนี้อธิบายแนวคิดสำคัญเกี่ยวกับการใช้ Metadata API เพื่อเข้าถึงรายการและแอตทริบิวต์ของคอลัมน์ Google Analytics

เกริ่นนำ

API ข้อมูลเมตาจะแสดงรายการคอลัมน์ (เช่น มิติข้อมูลและเมตริก) ที่แสดงใน API การรายงานของ Google Analytics และแอตทริบิวต์ หากคุณเพิ่งเริ่มใช้ API โปรดอ่านภาพรวมของ API ข้อมูลเมตาเพื่อดูข้อมูลเบื้องต้นเกี่ยวกับ API ข้อมูลเมตา

ก่อนที่คุณจะเริ่มต้น

Google Analytics API ทั้งหมดจะมีการเข้าถึงในลักษณะเดียวกัน ก่อนที่จะเริ่มต้นใช้งาน API ข้อมูลเมตา คุณควรทำดังนี้

  • อ่านหน้า ไลบรารีของไคลเอ็นต์เพื่อดูรายการไลบรารีไคลเอ็นต์ทั้งหมดของภาษาโปรแกรมที่ใช้งานร่วมกับ API ได้
  • อ่าน คู่มืออ้างอิงเพื่อดูข้อมูลเกี่ยวกับอินเทอร์เฟซ API และการเข้าถึงข้อมูลโดยไม่มีไลบรารีของไคลเอ็นต์

ไลบรารีของไคลเอ็นต์แต่ละรายการมีออบเจ็กต์บริการการวิเคราะห์รายการเดียวเพื่อเข้าถึงข้อมูล API ข้อมูลเมตาทั้งหมด หากต้องการสร้างออบเจ็กต์บริการเพื่อใช้กับ API ข้อมูลเมตา โดยทั่วไปคุณจะต้องทำตามขั้นตอนต่อไปนี้

  1. ลงทะเบียนแอปพลิเคชันใน คอนโซล Google API
  2. สร้างออบเจ็กต์บริการ Analytics และตั้งค่าคีย์ API

การลงทะเบียนและคีย์ API

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

การรับและการใช้คีย์ API

การรับคีย์ API ทำได้ดังนี้

  1. เปิดหน้าข้อมูลเข้าสู่ระบบในคอนโซล API
  2. API นี้รองรับข้อมูลเข้าสู่ระบบ 2 ประเภท สร้างข้อมูลเข้าสู่ระบบที่เหมาะสมกับโปรเจ็กต์ ดังนี้

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

      หมายเหตุ: เนื่องจาก API นี้ไม่มีเมธอดที่ต้องใช้การให้สิทธิ์ OAuth 2.0 คุณจึงอาจต้องการเพียงแค่รับคีย์ API ดังที่อธิบายด้านล่างนี้ อย่างไรก็ตาม หากแอปพลิเคชันของคุณเรียก API อื่นๆ ที่ต้องมีการให้สิทธิ์ผู้ใช้ คุณยังคงต้องใช้ข้อมูลเข้าสู่ระบบ OAuth 2.0 อยู่

      โปรดดูข้อมูลเพิ่มเติมในเอกสารประกอบเกี่ยวกับ OAuth 2.0

    • คีย์ API: คำขอที่ไม่ได้ระบุโทเค็น OAuth 2.0 ต้องส่งคีย์ API คีย์จะระบุโปรเจ็กต์และให้สิทธิ์เข้าถึง API, โควต้า และรายงาน

      API รองรับข้อจำกัดหลายประเภทเกี่ยวกับคีย์ API หากคีย์ API ที่คุณต้องการยังไม่มีอยู่ ให้สร้างคีย์ API ในคอนโซลโดยคลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์ API คุณจำกัดคีย์ก่อนนำไปใช้ในเวอร์ชันที่ใช้งานจริงได้โดยคลิกจำกัดคีย์ แล้วเลือกข้อจำกัดรายการใดรายการหนึ่ง

หากต้องการรักษาคีย์ API ให้ปลอดภัย ให้ทำตามแนวทางปฏิบัติแนะนำสำหรับการใช้คีย์ API อย่างปลอดภัย

หลังจากมีคีย์ API แล้ว แอปพลิเคชันจะเพิ่มพารามิเตอร์การค้นหา key=yourAPIKey ต่อท้าย URL คำขอทั้งหมดได้

คีย์ API ปลอดภัยสำหรับการฝังใน URL โดยไม่จำเป็นต้องมีการเข้ารหัสใดๆ

ข้อมูลโค้ดต่อไปนี้จะแสดงวิธีตั้งค่าคีย์ API สำหรับไลบรารีของไคลเอ็นต์ต่างๆ

Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

แอตทริบิวต์คอลัมน์

การตอบกลับ API ข้อมูลเมตามีพร็อพเพอร์ตี้ attributeNames ที่แสดงแอตทริบิวต์คอลัมน์ที่ถูกต้องทั้งหมด แต่ละคอลัมน์มีพร็อพเพอร์ตี้ attributes ที่มีชุดย่อยของแอตทริบิวต์ที่เกี่ยวข้องกับคอลัมน์ดังกล่าว

ตารางต่อไปนี้เป็นรายการแอตทริบิวต์ที่ถูกต้องทั้งหมด

กรณีการใช้งาน

คุณสามารถใช้ API ข้อมูลเมตาเพื่อแก้ปัญหา Use Case ต่อไปนี้

คอลัมน์ที่เลิกใช้งาน

หากเลิกใช้งานคอลัมน์ (เช่น มิติข้อมูลหรือเมตริก) แล้ว ระบบจะตั้งค่าแอตทริบิวต์ status ของคอลัมน์เป็น DEPRECATED

ข้อมูลโค้ดต่อไปนี้แสดงวิธีใช้แอตทริบิวต์ status เพื่อตรวจสอบว่าคอลัมน์เลิกใช้งานแล้วหรือไม่

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

หากเปลี่ยนชื่อ/นำคอลัมน์ออก ระบบจะตั้งค่าแอตทริบิวต์ status ของคอลัมน์เป็น DEPRECATED และอาจมีแอตทริบิวต์ replacedBy ตั้งค่าเป็น Id ของคอลัมน์การแทนที่

ข้อมูลโค้ดต่อไปนี้แสดงวิธีใช้แอตทริบิวต์ replacedBy เพื่อรับรหัสของคอลัมน์การแทนที่

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

ชื่อคอลัมน์

แอตทริบิวต์ uiName คือชื่อมิติข้อมูลหรือชื่อเมตริกที่ใช้ในอินเทอร์เฟซผู้ใช้ของ Google Analytics (เช่น อินเทอร์เฟซเว็บ)

ข้อมูลโค้ดต่อไปนี้แสดงวิธีเรียกข้อมูลชื่อ UI ของคอลัมน์

function getColumnName(column) {
  return column.attributes.uiName;
}

เสาชั่วคราว

คอลัมน์ชั่วคราวประกอบด้วยมิติข้อมูลหรือเมตริกที่มีดัชนีตัวเลข เช่น ga:goalXXStarts, ga:dimensionXX, ga:metricXX ฯลฯ คอลัมน์ที่มีเทมเพลตเป็นเทมเพลตจะมีแอตทริบิวต์ minTemplateIndex และ maxTemplateIndex ที่กำหนดช่วงดัชนี

ข้อมูลโค้ดต่อไปนี้แสดงวิธีตรวจสอบว่าคอลัมน์มีเทมเพลตเป็นเทมเพลตหรือไม่

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

ข้อมูลโค้ดต่อไปนี้แสดงวิธีเรียกข้อมูลรายการรหัสที่ถูกต้องสำหรับคอลัมน์ที่มีเทมเพลต

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

คอลัมน์ที่คำนวณ

คอลัมน์ที่มาจากการคำนวณคอลัมน์อื่นๆ จะมีแอตทริบิวต์ calculation เช่น การคำนวณสำหรับ ga:percentNewSessions คือ ga:newSessions / ga:sessions

ตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบว่ามีการคํานวณคอลัมน์หรือไม่ และวิธีดึงข้อมูลการคํานวณสําหรับคอลัมน์

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

คอลัมน์และกลุ่ม

แอตทริบิวต์ allowedInSegments ช่วยให้คุณตรวจสอบว่าสามารถใช้คอลัมน์ในพารามิเตอร์การค้นหากลุ่มได้หรือไม่

ตัวอย่างต่อไปนี้แสดงวิธีระบุว่าจะใช้คอลัมน์ในกลุ่มได้หรือไม่

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

เพิ่มในเวอร์ชัน API แล้ว

ใช้แอตทริบิวต์ addedInApiVersion เพื่อตรวจสอบว่าสามารถใช้คอลัมน์ใน API การรายงานของเวอร์ชันที่ระบุได้หรือไม่ ตัวอย่างเช่น เรียกใช้ฟังก์ชันต่อไปนี้เพื่อยืนยันว่าคอลัมน์ใช้ใน Core Reporting API V3 ได้ 

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

ETag จะรวมอยู่ในการตอบกลับจาก API ข้อมูลเมตาทุกรายการ ETag คือตัวระบุที่ใช้เพื่อแคชและอัปเดตการตอบกลับของ API ข้อมูลเมตาได้ วิธีนี้มีความสําคัญเนื่องจากข้อมูลในคอลัมน์ (เช่น มิติข้อมูลและเมตริก) อาจไม่มีการเปลี่ยนแปลงเป็นเวลานาน และทําการส่งคำขอและอัปเดตที่ไม่จำเป็นเมื่อใช้ข้อมูลที่แคชไว้ได้ จึงไม่มีประสิทธิภาพ

หากคุณจัดเก็บ ETag ของ คอลเล็กชันคอลัมน์ จะมีการใช้งาน 2 วิธีเป็นหลัก ได้แก่ การตรวจสอบว่าการตอบกลับจาก API ข้อมูลเมตาที่แคชไว้เป็นข้อมูลล่าสุดหรือไม่ และเพื่อรวมไว้เป็นส่วนหนึ่งของคำขอ API ข้อมูลเมตา

การตรวจสอบการตอบกลับที่แคชไว้

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

หากต้องการดึงเฉพาะค่า ETag จาก API ข้อมูลเมตา ให้ตั้งค่าพารามิเตอร์การค้นหาช่อง เป็น etag เมื่อส่งคำขอ ดูตัวอย่าง

การใช้ ETag กับคำขอ API

หากมีคอลเล็กชันคอลัมน์ที่แคชไว้ คุณจะรวมค่า ETag ของคอลเล็กชันนั้นไว้ในคำขอ API ข้อมูลเมตาได้โดยการตั้งค่าช่องส่วนหัว HTTP ของ If-None-Match API ข้อมูลเมตาจะตรวจสอบค่า ETag และตอบกลับด้วยเวอร์ชันที่อัปเดตของทรัพยากรและสถานะ HTTP ของ 200 OK หรือการตอบกลับว่างเปล่าที่มีสถานะ 304 Not Modified หากเวอร์ชันที่แคชไว้เป็นปัจจุบัน