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

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

บทนำ

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

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

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

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

ไลบรารีของไคลเอ็นต์แต่ละรายการจะมีออบเจ็กต์บริการข้อมูลวิเคราะห์รายการเดียวเพื่อเข้าถึงข้อมูล API ของข้อมูลเมตาทั้งหมด หากต้องการสร้างออบเจ็กต์บริการเพื่อใช้กับ Metadata 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>

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

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

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

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

คุณสามารถใช้ Metadata 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 จะรวมอยู่ในทุกการตอบกลับของ Metadata API ETag คือตัวระบุที่ใช้แคชและอัปเดตการตอบกลับ Metadata API ได้ ซึ่งมีความสําคัญเนื่องจากข้อมูลคอลัมน์ (เช่น มิติข้อมูลและเมตริก) จะไม่เปลี่ยนแปลงเป็นเวลานานและอาจสร้างคําขอและการอัปเดตที่ไม่จําเป็นเมื่อใช้ข้อมูลที่แคชไว้ได้

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

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

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

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

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

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