將我的資料分享給第三方

為了符合目前的北美能源標準委員會 （NAESB） 能源服務提供商介面 （ESPI） 授權標準，PG&E 已實施 OAuth 2.0 授權架構，以授權資料存取。下圖說明客戶如何啟動授權、選擇範圍參數，然後提交授權。

除了以下資訊以外的其他參考資料：

下載 ESPI OAuth 2.0 序列圖（PDF，193 KB）
在 Github 檢視綠色按鈕資料 SDK

注意：對於 Community Choice 彙總器，只需要 client_access_token 來請求資料（透過 2-Legged OAuth），並且以下不適用。

在第三方網站啟動授權

若要開始從第三方網站取得授權，如上圖所示，授權代碼要求是透過將客戶的瀏覽器從您的第三方網站重新導向至 PG&E 的授權伺服器授權端點 URL，並具有適當的要求參數，如下所示。重新導向時，客戶將會收到驗證用的 PG&E 登入頁面，接著是授權資料存取至第三方的授權頁面：

authorizationServerAuthorizationEndpoint URI （含要求參數）
https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri={redirect_uri}&response_type=code&state={optionalState}

• 強制要求參數：
  • client_id = 來自您共用我的資料註冊里程碑（即 client_id/client_secret 配對）的客戶 ID。
  • redirect_uri = 您在共用我的資料註冊中指定的重新導向 URL（URL 必須相符）。
    注意： 我們建議按照以下範例將 URL 編碼應用於 redirect_uri。
  • response_type = 程式碼 （靜態值）
• 選擇性要求參數（們）：
  • state = OAuth 2.0 標準所允許之選擇性不透明狀態參數，該參數會連同授權碼一起傳回以協助維持狀態。例如，第三方可能使用狀態參數以唯一識別客戶發起，並防止跨網站偽造。
  • login={guest} 提供選項供第三方將客戶重新導向至 PG&E 的 My Energy 登入或訪客存取標籤，作為線上授權流程的一部分。

範例：驗證代碼要求

取得：https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri=https%3A%2F%2Fthirdparty.com%2FredirectUrl&response_type=code&state=pge12advertisement

注意：上面的 redirect_uri 參數範例已套用 URL 編碼（即 https://thirdparty.com/redirectUrl 的 URL 編碼）

如果您按上述方式提出有效請求，且客戶成功驗證並授權，則客戶隨後將重新導向至具有授權代碼、（授權）範圍參數和可選狀態參數（如果作為授權請求的一部分提供）的 redirect_uri，具體如下：

https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219&scope=FB=1_3_8_13_14_18_19_31_32_35_37_ 38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment ；IntervalDuration=900_3600；BlockDuration=每日；HistoryLength={3P Registered historical length}；AccountCollection={count of authorizedSAs}；BR={ThirdPartyID}；dataCustodianId=PGE &state=pge12廣告

注意：授權代碼為短期（600 秒內到期），之後必須交換為存取令牌/重新整理令牌組，以完成授權並允許持續的資料存取。請參閱下一節（第 2 節），瞭解存取金鑰/重新整理金鑰要求的詳細資料。

上述（授權）範圍參數作為對授權代碼請求、存取令牌請求以及授權 API 的回應的一部分予以返回。此範圍參數允許傳達客戶授權的最終範圍。具體而言，範圍參數包括對應至 PG&E 所支援之客戶授權資料群組選項的 "AdditionalScope" 值 （例如，"Usage"、"Billing"、"Basic"、"Account"、"Program Enrollment"）。範圍參數值會依據下列參考文件進一步擷取：下載支援的功能模組範圍字串對應 按一下至 2.0 （PDF， 222 KB）。

錯誤情境

第三方實施錯誤：如果在請求授權代碼時 client_id 或 redirect_uri 的必要請求參數無效或缺失，客戶將看到解釋性訊息以及標準的 HTTP 400 系列錯誤。同樣地，如果 response_type 的必要要求參數遺失或無效，則系統會使用 OAuth 2.0 定義的 "invalid_request" 錯誤參數將客戶重新導向回您的 redirect_uri，如果該參數是原始授權代碼要求中最先提供的，則會選擇狀態參數。

拒絕授權的客戶：當第三方將客戶重新導向至 PG&E 進行授權時，客戶可以選擇透過登入頁面和授權頁面的“取消”按鈕拒絕。在這種情況下，客戶將被重新導向回您的 redirect_uri，並附上 OAuth 2.0 定義的 "access_denied" 錯誤參數，表示客戶拒絕授權。此外，如果作為原始授權碼請求的一部分而先提供，則將返回可選狀態參數。

在 PG&E 啟動授權

當客戶從 PG&E 的客戶入口網站 "您的帳戶" 開始，然後瀏覽至 Share My Data 登陸頁面時，系統會顯示已註冊和可見的第三方下拉式清單。如上圖第二圖所示，在客戶從已註冊的第三方清單中選擇第三方，並選擇“下一步”時，該客戶將被重新導向到第三方的已註冊“第三方入口網站 URI”，然後客戶可以繼續進行前一節所述的第三方發起的OAuth流程。

注意：有些第三方詢問如何簡化此使用案例的客戶體驗（即 PG&E 網站上發起的授權），因此在從下拉選單中選擇第三方時，似乎直接帶至授權頁面。為了促進此類客戶體驗，第三方可以選擇將其第三方入口網站 URI（透過共用我的資料管理註冊頁面）設定為自動將客戶重新導向回 PG&E 的端點，作為授權代碼請求的一部分。自動重新導向回 PG&E 的授權伺服器授權端點後，客戶將略過客戶登入頁面（因為他們已經登入），並直接前往授權頁面。對於在 2018 年 6 月底發佈 Share My Data Click Thru 2.0 之前註冊的某些第三方，只需定義第三方入口網站 URI 以等於不再使用的“第三方範圍選擇螢幕” URI（未來發佈時要淘汰的欄位）即可完成。

相反地，有些第三方可能希望在客戶要求授權代碼之前重新導向到他們的第三方入口網站 URI 時，首先進行互動和篩選客戶端，因此上述方法只是一個建議。

若要取得存取密碼卡，請使用收到的授權碼，並按照下述方式使用要求參數致電以下端點。如上所述，授權碼為簡版，將於 10 分鐘（600 秒）後到期，因此請確保在收到授權碼時立即要求存取碼。

authorizationServerAuthorizationEndpoint：https://api.pge.com/datacustodian/oauth/v2/token

• 必要要求參數：
  • grant_type = authorization_code（靜態值）
  • 代碼 = 回應授權代碼請求而收到的授權代碼
  • redirect_uri = 您在共用我的資料註冊中指定的重新導向 URL（URL 必須相符）。
    注意：與授權碼請求一樣，我們建議將 URL 編碼套用於 redirect_uri。

範例：存取金鑰要求
POST： https://api.pge.com/datacustodian/oauth/v2/token?grant_type=authorization_code&code={authorizationcode}&redirect_uri={redirect_uri}

新增基本授權標頭參數，並使用 Base64 編碼套用的 "clientID：clientSecret"

注意： clientId：clientSecret 值對應於您共用我的資料註冊里程碑中提供的客戶 ID 值。
標題參數的格式如下：
參數名稱：授權
參數值：基本 "base64encoded string"

成功的回應將如下所示：

＜回應 xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
＜存取_金鑰>774ff105-7ad5-40c8-a6ec-f60675dc0e41 ＜到期日_in>3600
998c6654-5b3b-4385-af4f-4e5c46c1bb04
scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment；IntervalDuration=900_3600；BlockDuration=每日；HistoryLength={3P Registered historical length}；AccountCollection={count of authorized SAs}；BR={ThirdPartyID}；dataCustodianId=PGE
資源URI：{ResourceURI}，例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
authorizationURI：{AuthorizationURI} 例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
customerResourceURI：{customerResourceURI} 例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
Bearer

注意：存取密碼卡將在 3600 秒（1 小時）後到期，而對應的重新整理密碼卡則會在 1 年內到期。有關取得新的存取金鑰/重新整理金鑰配對的詳細資訊，請參閱下一節 3。

儲存存取權並重新整理權杖配對。
若要要求初始歷史資料和持續的每日資料，請訪問資料存取 。

根據最佳做法，存取金鑰是短期金鑰（1 小時），而對應的重新整理金鑰是長期金鑰（1 年），您可以在存取金鑰過期時用來取得新的存取金鑰/重新整理金鑰組合。若要為現有的未過期授權取得新的存取金鑰和重新整理金鑰配對，請使用目前的重新整理金鑰，並按照下述參數致電以下端點。

authorizationServerAuthorizationEndpointhttps://api.pge.com/datacustodian/oauth/v2/token ？grant_type= refresh_token&refresh_token={current_refresh_token}

範例：重新整理金鑰要求
POST：https://api.pge.com/datacustodian/oauth/v2/token?grant_type= refresh_token&refresh_token={current_refresh_token}

新增基本授權標頭參數，並使用 Base64 編碼套用的 "clientID：clientSecret"

注意： clientId：clientSecret 值對應於您共用我的資料註冊里程碑中所提供的 clientID 值。
標題參數的格式如下：
參數名稱：授權
參數值：基本 "base64encoded string"

成功的回應將如下所示：
{
"access_token"： "677e6ef8-1e1a-43f0-85b8-5692fcbc72b2"，
"token_type"："無記名"，
"到期日_in"： 3600，
"refresh_token"： "0eef9a9f-60c6-40bb-b33f-910e322c0298"，
"範圍"： "scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_
計劃註冊；IntervalDuration=900_3600；BlockDuration=每日；HistoryLength={3P Registered historical length}；AccountCollection={count of authorized SAs}；BR={ThirdPartyID}；dataCustodianId=PGE"，
"resourceURI"： "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/test",
"authorizationURI"： "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/test"
}

注意：同樣，客戶存取金鑰是短期金鑰（1 小時），而其對應的重新整理金鑰是長期金鑰（1 年），您可以在客戶存取金鑰到期時用來取得新的客戶存取金鑰/重新整理金鑰組。若要取得新的用戶端存取金鑰/重新整理金鑰組，請參考上述相同步驟。

客戶將能夠透過執行以下操作來更新其授權：

• 從授權中移除服務 ID
• 延長授權期限的結束日期
• 取消授權

注意：客戶只能透過登入其線上 PG&E 帳戶並遵循必要步驟，來變更授權。如果採取任何這些行動，我們將透過您在註冊時提供的通知 URI 通知您。

有管理和檢視客戶授權詳細資料的選項：

• 您可以在第三方層級 （關於所有授權的詳細資訊） 的 https://api.pge.com/GreenButtonConnect 或 /espi/1_1/resource/Authorization 的個別客戶授權層級，使用 client_access https://api.pge.com/GreenButtonConnect_token 呼叫授權 API （http GET operation）。
• 此外，您也可以透過第三方入口網站登入您的 Share My Data 帳戶，並輸入您所搜尋授權的訂閱 ID，以手動方式檢視個別授權詳細資料。

如果您不想再存取與授權相關的資料，可選擇取消授權的方法：

• 您可以在 https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID} 使用 client_access_token 呼叫授權撤銷 API （http DELETE 操作）。
• 或者，您可以透過第三方入口網站登入您的 Share My Data 帳戶，並輸入您想要取消的授權訂閱 ID，以手動取消授權。

注意：客戶將收到通知，表示您已選擇取消其授權。此外，一旦取消授權，便無法撤銷該動作。

• PG&E 將傳送通知至您在註冊時提供的通知 URI。通知包含對應於已預先封裝資料的 URI，可供您返回，並在提供的 URL 上要求。資料已預先封裝，並在以下兩種情況下發送通知：（1） 您已在註冊檔案中選擇“資料已就緒時通知我”，在這種情況下，我們將把最新的每日資料與過去日期的任何更正進行封裝，或者（2）您提前提出了一個臨時非同步請求，請求的資料現已準備就緒。
• 情境 1 說明於 "DATA ACCESS：以下資料存取方法圖表中的每日訂閱部分，情境 2 顯示於資料存取下方：下方相同圖表的 AD HOC REQUEST （ASYNCHRONOUS）" 部分。

請記住，在資料要求中使用的存取金鑰、用戶端存取金鑰及其對應的重新整理金鑰的存留時間。根據最佳做法，存取金鑰是短期金鑰（1 小時），而重新整理金鑰是長期金鑰（1 年），您可以在存取金鑰過期時用來取得新的存取金鑰/重新整理金鑰組合。同樣地，用戶端存取金鑰是短期金鑰（1 小時），而其對應的重新整理金鑰是長期金鑰（1 年），您可以在用戶端存取金鑰過期時用來取得新的用戶端存取金鑰/重新整理金鑰組。如需取得新金鑰組的詳細資訊，請參閱授權詳細資料標籤中的步驟 3 要求新存取權杖。 前往授權詳細資料

若客戶授權您接收"帳戶資訊"（帳戶 ID、服務協議 ID 和服務開始日期）和/或"基本資訊"（即客戶名稱和服務地址），則您可以透過符合上述提供的架構， RetailCustomer.xsd 的 ESPI 定義 RetailCustomer API 來要求此類客戶資訊。

同步（標準和 EEF 第三方）

要求客戶資料的一種方法是使用同步 API 要求客戶資料的單一客戶授權之客戶資訊 （亦即零售客戶）：

同步要求 URL 範例：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}

RetailCustomerID = 您在 OAuth 授權序列結束時收到的 RetailCustomerID，以取得存取權杖。RetailCustomerID 是 Token 回應中 customerResourceUri 路徑參數的一部分。（RetailCustomerID=訂閱ID）

HTTP 標頭 = 授權：承載 {此授權的存取權杖}

回應 = 您將同步回傳該 RetailCustomerID 的資料。資料符合 RetailCustomer.xsd

注意：同步零售客戶 API 位於個別零售客戶層級，對應於單一客戶授權。

供參考：下面的階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層。

您也可以透過非同步 API 來要求客戶資料，以便針對您所有客戶資料 （例如零售客戶） 的客戶授權要求客戶資訊。

為了支援非同步要求，您的應用程式將需要支援我們將寄給您的通知後（根據您在註冊時提供的通知 URL）。

非同步要求 URL 範例：
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}

大量 ID = 在註冊測試期間擷取的應用程式資訊資源中提供的大量 ID。（批量 ID=客戶 ID）

HTTP 標頭 = 授權：認證 {註冊測試期間擷取用戶端存取權杖}

回應 = HTTP 狀態代碼 202 （這是一個非同步請求，當資料就緒時，回應將發佈到通知 URL）。一旦資料準備就緒，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}？correlationID={correlationID}

使用用戶端存取權杖在上述 URL 上執行 GET 以取得資料。

供參考：下面的階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層。

最後，您可以使用每日訂閱模式，每天取得最新的客戶資訊 （亦即，在註冊時勾選 "通知我資料已就緒 （每日）" 核取方塊）。

為支援每日訂閱模式，您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）。

一旦資料準備就緒，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}？correlationID={correlationID}

使用用戶端存取權杖在上述 URL 上執行 GET 以取得資料。

下方階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層，以供參考。

如果您獲得客戶授權接收“使用資訊”和/或“帳單資訊”，您可以透過訂閱 API 請求此資料，該 API 的資料符合上述提供的 espiDerived.xsd 架構。

同步臨時請求（標準和 EEF 第三方）

若要要求歷史資料 （包括間隔使用資料和帳單資料），其中一種方法是使用同步 API，並在 Zulu 時間內包含適當的開始和結束日期要求參數。

同步要求 URL 範例：
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}？published-min={startDate}&published-max={endDate}

published-min = 將套用至此資料擷取要求的開始日期。日期是 Zulu time of yyyy-MM-ddTHH：mm：ssZ（IETC RFC 3339 格式）

published-max = 將套用至此資料擷取要求的結束日期。日期是 Zulu time of yyyy-MM-ddTHH：mm：ssZ（IETC RFC 3339 格式）

注意：對於接受發佈-最大和發佈-最小日期參數的 API 請求，預設值為 T-1（請求日期減 1 天）。對於使用摘要請求（例如，.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/UsageSummary），我們建議提供 30 天或更長時間的範圍，以確保有與該期間重疊的可用帳單，否則不會傳回任何資料。

訂閱 ID = 您在 OAuth 授權序列結束時收到的訂閱 ID，以取得存取權杖。訂閱 ID 是 Token 回應中 resourceURI 參數的一部分。（訂閱 ID=零售客戶 ID）

UsagePointID = 上述訂閱 ID 下的 UsagePoint。您可以致電以下 API URL 並在授權標題中提供該訂閱的存取權杖，以取得特定訂閱的所有使用點數：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint

HTTP 標頭 = 授權：此訂閱的證卡 {存取權杖}

回應 = 您將在請求的期間同步返回該使用點的資料。它將同時包含間隔使用資料 （） 和帳單資料 （）。

同步使用 API（如 URL 構造所示，以使用點 ID 結尾）處於個別使用點層級（即服務協議層級），因此應用程式將透過屬於給定客戶授權（即訂閱）的每個使用點 ID 循環請求。

對同步要求的回應會同時傳回與要求日期範圍相關聯的間隔資料 （低於），以及與要求日期範圍 （低於） 重疊的任何每月使用總數和帳單。

• 間隔讀取包含間隔 （15 分鐘/小時） 電力使用和間隔 （每日） 氣體使用資料
• 使用情況摘要包含每月使用情況總計和帳單詳情（如經授權）

在回應中，您會找到與我們的 ESPI 資料元素對應表相對應的資料元素

下方階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層，以供參考。

以下是有關這些資料元素的一些重要說明：

• 間隔封鎖為 1 天
• 間隔讀取 （間隔區塊下方） 包含實際的 15 分鐘/小時電力使用值和每日瓦斯使用值
• 對於現場發電的電力客戶 （例如太陽能），flowDirection 元件會指示已交付 （供應） 和已接收 （發電） 的使用資料。對於配置為僅讀取淨使用量（即現場無代數）的儀表的客戶，flowDirection 元素表示使用量為淨量（已交付差異減去接收差異）：
  • 流量方向 1 = 已傳送 （供應給客戶的能源）
  • 19 的流量方向 = 已接收 （淨發電流回 PG&E 網格）。（注意，值為絕對值）
  • 4 的流量方向 = 淨（已交付減去 – 已接收）
• 特別注意十倍數乘數和計量單位（uom）的功率，以確保正確的使用讀數

批次訂閱（標準和 EEF 第三方）

您也可以透過非同步 API，針對屬於單一客戶使用/帳單資料 （即訂閱） 授權的所有使用點要求使用資料。

為支援臨時非同步請求（即一次使用多個點），您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）

非同步要求 URL 範例
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}？published-min={startDate}&published-max={endDate}

訂閱 ID = 您在 OAuth 序列結束時收到的訂閱 ID，以取得存取權杖。訂閱 ID 是 Token 回應中 resourceURI 參數的一部分

published-min = 將套用至此資料擷取要求的開始日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

published-max = 將套用至此資料擷取要求的結束日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

HTTP 標頭 = 授權：此訂閱的證卡 {存取權杖}

回應 = HTTP 狀態代碼 202 （此為非同步請求，當資料就緒時，回應將發佈到通知 URL）

一旦資料準備就緒，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

批次訂閱（標準和 EEF 第三方）
您也可以透過批次批量非同步 API，針對所有客戶對使用/帳單資料 （即訂閱） 的授權來要求使用和帳單資訊。

批次大量要求 URL 範例
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？published-min={startDate}&publishedmax={endDate}

大量 ID = 在註冊測試期間擷取的應用程式資訊資源中提供的大量 ID。（批量 ID=客戶 ID）

published-min = 將套用至此資料擷取要求的開始日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

published-max = 將套用至此資料擷取要求的結束日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

HTTP 標頭 = 授權：承載 {用戶端存取權杖}

回應 = HTTP 狀態代碼 202 （此為非同步請求，當資料就緒時，回應將發佈到通知 URL）

一旦資料準備就緒，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

最後，您可以使用每日訂閱模式取得最新的使用和帳單資訊，包括客戶授權期間過去日期的更正（即在註冊時勾選“資料就緒時通知我（每日）”核取方塊）。

為支援每日訂閱模式，您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）。

一旦資料準備就緒，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

2024 年 6 月 20 日

PG&E 與第三方服務供應商共用我的資料平台 （SMD），用於客戶授權資料共用，我們發布了電錶 ID 增強的第 2 階段，允許識別與電間隔電錶資料相關的個別電錶 ID。  

此增強功能對於與一項服務協議有關聯之多個儀表的使用者情境特別有用。

第 1 期：  2023 年 3 月發佈 - 修改受影響的 API，開始在 標籤下新增 值以及傳回的回應中的 值。SerialNumber 值與 utcNumber 值之間有一對一的對應。

此資訊允許使用這些 API 的廠商在發佈第 2 階段增強之前，使用 utcNumber 以及與其客戶群特定儀表相關的序號值來建立記錄儲存。

第 2 期：2024 年 6 月 20 日發佈 - 以 utcNumber 取代目前編碼的儀錶描述性值64 格式的儀錶讀取 ID 值。一旦這些變更完全實施，Share My Data 使用者將具有更好的能力，可以連結到特定儀表間隔使用量，如果同一商品的多個儀表連結到內部部署的單一服務協議，則連結到產生使用量的特定儀表 ID。 

以下 API 受到第 2 階段變更的影響

受影響的 API：

.../espi/1_1/資源/訂閱/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading

.../espi/1_1/資源/訂閱/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}

.../espi/1_1/資源/訂閱/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}/IntervalBlock

.../espi/1_1/資源/訂閱/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading/{MeterReadingID}/IntervalBlock/{IntervalBlockID}

具有間隔讀取的所有其他 API 均保持不變，並在兩個流向和所有儀表上代表儀表間隔的 SUM。

在發佈之前，MetrReadingID 欄位已編碼 Base64，傳回的值顯示如下：

MeterReadingID= TnpJNmJuVnNiRG96TmpBd09qRT06MTox

從 Base64 格式解碼為：  NzI6bnVsbDozNjAwOjE =：1：1

這會顯示 readingTypeID：rownum：count，而 readingTypeID 值再次從 Base64 解碼為：

72：null：3600：1，其中值為uom：相位：intervalLength：flowDir

UOM=72，相位=空，間隔長度=3600，流量Dir=1（已傳送）

在階段 2 中，儀錶讀取 ID 欄位附加額外的字元，經過初始解碼後，會傳回下列範例結果

MeterReadingID=TnpJNmJuVnNiRG96TmpBd09qRT06MToxOjQ0MTEzMTA1NDYgICAgICAgICAg

從 Base64 解碼一次：  NzI6bnVsbDozNjAwOjE =：1：1：4411310546， 

這顯示 meter_UUID 為 4411310546，且此值應符合 RetailCustomer API 中 標籤下的 值。

“NzI6bnVsbDozNjAwOjE=：1：1：” 的值 是讀TypeID：rownum：count，即列號為 1，而計數為 1 與 PG&E 的內部資料庫記錄有關。readingTypeID 再次解碼為：

72：null：3600：1，其中值為uom：phase：intervalLength：flowDir

UOM=72，相位=空，間隔長度=3600，流量Dir=1（已傳送）

此變更允許使用者在間隔讀取中指定實體儀表和相關流量方向。請注意，所有 XML 檔案現在都會攜帶新的 MeterReadingID 值，並將套用新的 Phase 2 編碼形式。分享我的資料會告知所有使用 MeterReadingID 進行任何 API 呼叫的供應商，進行下列 API 呼叫以取得新的 MeterReadingID：.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/MeterReading

2023 年 3 月 20 日

新功能：

1. 發佈新的 API HTTP 回應代碼 （204） 用於同步和非同步 API 呼叫，以指示何時沒有資料可用於請求範圍。
2. 支援 x-transaction header 標籤，可在要求的檔案準備就緒時，透過將此值連同關聯 ID 傳回來支援將 PG&E 的回應連結至特定的非同步 API 呼叫。
3. 透過為多個儀表至單一服務協議情境提供電間隔資料，改善了 UsagePoint/MeterReadingID API 的額外資料精細度。
4. 為預估間隔資料的讀取品質指標值提供額外的清晰度，以描述該間隔使用的估計類型。表示已套用估計邏輯的新值如下：
   
   

5. RQI 值和說明

   0 - 有效：已通過所有必要驗證檢查並全部通過或經過驗證的資料

   7 - 手動編輯：由人員取代或核准

   8 - 使用參考日估計：資料值被使用相同類型測量的歷史資料分析機器計算值取代

   9 - 使用線性插補估計：資料值是根據前後的讀數使用線性插補計算

   10 - 可疑：一項或多項檢查未通過的資料

   11 - 衍生：已計算（使用邏輯或數學運算）的資料，不一定直接測量

   12 - 預測（預測）：已計算為預測或預測未來讀數的資料

   13 - 混合：表示此讀數的品質具有混合特性

   14 - 原始：未經過驗證、編輯和估計流程的資料。備註 MV90 儀錶 RQI 指示燈將維持在 14 的狀態，作為最終 RQ 狀態

   15 - 天氣標準化：已調整數值以考慮天氣，比較不同氣候中的使用情況

   16 - 其他：指明除定義者外套用的特徵

   17 - 已驗證：已驗證且可能依據核准程序編輯和/或估計的資料

   18 - 已驗證：未通過至少一項所需驗證檢查但確定為代表實際使用的資料

   19 - 營收品質：適用於帳單用途且可接受 【可能是 ESPI 標準的延期，不屬於原本的 ESPI】

    

6. 在共用我的資料第三方廠商入口網站中發佈廠商 API 使用指標。

2018 年 11 月 15 日

新功能：

1. 已新增客戶類別指示器。每個授權的 SAID 將被識別為 RES、AGR、COM/IND 或其他。
2. 計費和使用 API 將更新為接受更新上限和更新上限查詢參數 （可替代已發佈上限和已發佈上限）。傳回的資料將是所有在更新最大值和更新最小值參數內發生的變更。
3. 將第三方的 5 位數大宗 ID 替換為第三方的客戶 ID 以進行線上授權流程。
4. 提供選項供第三方將客戶重新導向至 PG&E 的帳戶登入或來賓存取標籤，作為線上授權流程的一部分。
5. 改善 PG&E 的 Share My Data 客戶儀表板，讓客戶更容易與第三方檢視所有現有的資料分享授權。

2018 年 9 月 27 日

新功能：

作為 PG&E 擴展資料集 （EDS） 專案的一部分，PG&E 向規則 24 資料集新增了新資料元素，相應的新資料元素也引入了規則 25 資料集。包含 PG&E 擴展規則 25 資料集的特定資料元素，在下面以指定 EDS 列出：

規則 25 資料元素

備註
帳戶元素
帳戶名稱
客戶地址
帳戶 ID
EDS：中斷區塊
服務元素
PG&E UUID
服務 ID
服務狀態的未來變更
SA 狀態
服務開始日期
服務地址
目前服務費率
歷史帳單服務費率
關稅選項（醫療基準、CARE、FERA、TBS、CCA_TBS、Solar Choice
目前服務電壓和商品歷史計費服務電壓
服務計量表編號
服務計量表數量
計量表類型
電流計讀取週期
歷史帳單計量表讀取週期
現場產生指示器時的目前待命費率選項
歷史帳單備用費率選項
EDS：客戶類別指示器
歷史帳單元素
帳單開始日期
帳單結束日期
帳單費用總額（$）
帳單總計 kWh
EDS：服務供應商名稱
歷史帳單層級明細（若有）
EDS：明細項目帳單期間
EDS：姓名（超過基準期 1%-30%）
EDS：音量 （1234.2）
EDS：費率（$0.032/kWh）
EDS：費用 （$100.23）
歷史帳單 TOU kWh 明細（ABS-TX 計費除外）
EDS：明細項目帳單期間（用於 TOU 明細）
EDS：名稱（TOU 費用）
EDS：音量 （1234.2）
EDS：費率（$0.032/kWh）
EDS：費用 （$100.23）
歷史帳單需求明細
EDS：明細項目帳單期間（用於需求明細）
EDS：名稱
EDS：音量 （1234.2）
EDS：費率（$0.032/kWh）
EDS：費用 （$100.23）
歷史帳單明細項目
EDS：明細項目帳單期間
EDS： 收費名稱（DWR Bond Charge）
EDS：音量 （1234.2）
EDS：單位（kWh）
EDS：費率（$0.032/kWh）
EDS：費用 （$100.23）
歷史使用間隔
間隔使用開始
預設間隔持續時間（秒）
間隔使用量 （1234.2）
單位 （kWh/熱）
公用事業需求回應計畫
（DR）程式名稱
無財務義務的最早終止日期
無論財務義務為何，最早終止日期
DR 程式狀態
DR 方案註冊日期
DR 方案取消註冊日期
資料元素
商品
當地時間參數（DST 詳細資料）
預設資料品質
能量方向
十乘數的功率（用於間隔使用值）
十倍乘數（用於計費需量）
十倍乘數（用於計費總用量）
間隔長度（使用讀數）
帳單總金額的幣別
電力間隔 TOU 指示燈

2018 年 6 月 28 日

作為 Click-Through 專案的一部分以及 Share My Data Platform 的持續改善，PG&E 於 2018 年 6 月 28 日推出 Click-Through Phase 2。

新功能：

影響第三方的最關鍵變更是符合 OAuth 2.0 協議的變更（PG&E 消除了最初一系列重新導向）。 詳情如下。

重要事項： 第三方必須變更其現有的 OAuth 實作。PG&E 的 Click-Through Phase 2 變更無法向後相容，因此第三方必須隨著 PG&E 的實施同時實施變更。若無實施，目前的客戶授權流程將於 2018 年 6 月 29 日停止運作。 但是，現有的授權不受影響。

1. 為了符合 OAuth 2.0 協議，PG&E 減少了授權的重新導向步驟數。客戶登入和提交授權的初始重新導向至 PG&E 已與授權代碼請求合併如下：
   • 如以下範例所示，第三方授權碼要求現在包括將客戶的瀏覽器重新導向至 PG&E 的新authorizationServerAuthorizationEndpoint URI，以及適當的要求參數：
     取得 https://sharemydata.pge.com/myAuthorization?client_id=xxxxx&redirect_uri={redirect_uri}&response_type=code&state={optionalState}
   • 下列指標已淘汰：https://api.pge.com/datacustodian/oauth/v2/authorize...
     
2. 處理授權代碼要求之訊息時出現新的錯誤，其範圍參數遺失或無效，如下所示：
   • 如果所需的 client_id 或 redirect_uri 參數遺失或無效，向客戶顯示帶有解釋訊息的 （http 400） 錯誤
   • 如果所需的 response_type 參數遺失或無效，客戶將使用 "invalid_request" 錯誤參數 （附加到 redirect_uri） 重新導向回第三方的 redirect_uri
     
3. 對於具有現有線上授權的客戶，第三方可以要求新的存取_金鑰/refresh_金鑰組，作為取代現有授權的一部分（即相同第三方的線上授權和客戶組合）。此功能可解決第三方遺失 access_token/refresh_token 配對或以其他方式需要根據客戶核准變更原始授權範圍的情況。
   • 對於重新授權請求，當第三方重新導向到 PG&E 進行授權時，客戶會看到新的授權頁面而不是“管理授權”頁面
   • 在客戶授權後，第三方會收到通知，告知其註冊的 URL 舊訂閱 ID 已取消 （通知包含舊訂閱 ID 的授權 API URL 端點）
     
4. 客戶透過驗證頁面或授權頁面上的 "cancel" 按鈕退出，並使用 "access_denied" 錯誤參數重新導向回第三方的 redirect_uri （附加至 redirect_uri）
5. 對於在 上以 "可見性" 設定註冊的第三方，因此包含在已註冊的第三方清單中的第三方，客戶將看到他們何時進入 PG&E 線上帳戶，並導覽至共用我的資料登陸頁面：
   • 對於登入其 PG&E 線上帳戶並導覽至共用我的資料登陸頁面，然後在從已註冊的第三方清單中選擇第三方時，重新導向至第三方已註冊的第三方入口網站 URI。屆時，客戶可以繼續進行第三方發起的 OAuth 流程。通過此路徑時，從第三方下拉式清單中選擇第三方後，客戶將不再看到授權頁面，而是被重新導向至第三方註冊的第三方入口網站 URI，在該處他們可以開始第三方發起的 OAuth 流程
   • ‭‬注意：部分第三方已詢問如何簡化此使用案例的客戶體驗 （即 PG&E 網站上啟動的授權），因此在從下拉清單中選取第三方時，似乎直接將它們帶往授權頁面。為了促進此類客戶體驗，第三方可以選擇將其第三方入口網站 URI（透過共用我的資料管理註冊頁面）設定為自動將客戶重新導向回 PG&E 的端點，作為授權代碼請求的一部分。自動重新導向回 PG&E authorizationServerAuthorizationEndpoint後，客戶將略過客戶登入頁面 （因為他們已經登入），並直接前往授權頁面。對於在 Share My Data Click Thru 2.0 版本之前已註冊的部分第三方，只需定義第三方入口網站 URI 以等於不再使用的 "第三方範圍選擇畫面"URI （舊的 SMD 註冊欄位將於未來版本中淘汰） 即可完成。
     相反地，有些第三方可能希望在客戶在要求授權代碼之前重新導向到他們的第三方入口網站的 URI 時，首先在他們那邊進行互動和篩選，因此上述方法只是一個建議。
     
6. SMD 現在將提供增強範圍參數詳細資料，作為對授權代碼請求、存取令牌請求和授權 API 的回應的一部分。增強範圍參數允許傳達客戶授權的最終範圍。具體而言，範圍參數包括對應至 PG&E 所支援之客戶授權資料群組選項的 "AdditionalScope" 值 （例如 "Usage"、"Billing"、"Basic"、"Account"、"Program Enrollment"）。根據以下文件進一步擷取範圍參數值：下載支援的功能模組範圍字串對應 按一下至 2.0 （PDF）
   
   以下金鑰回應範例說明一些可能的範圍參數值。
   • 動態密碼卡回應範例：
     ＜回應 xmlns="https://api.pge.com/datacustodian/oauth/v2/token">
     ＜存取_金鑰>774ff105-7ad5-40c8-a6ec-f60675dc0e41 ＜到期日_in>3600
     998c6654-5b3b-4385-af4f-4e5c46c1bb04
     scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment；IntervalDuration=900_3600；BlockDuration=每日；HistoryLength={3P Registered historical length}；AccountCollection={count of authorized SAs}；BR={ThirdPartyID}；dataCustodianId=PGE
     資源URI：{ResourceURI}，例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
     authorizationURI：{AuthorizationURI} 例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
     customerResourceURI：{customerResourceURI} 例如：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
     Bearer
     
     
7. 第三方現在可以註冊，透過新的 "Program Enrollment" 資料群組接收授權的計劃 Enrollment 資訊。間隔計量和非間隔計量客戶均有資格授權為 SMD 點選至階段 2 共用資料。計劃 Enrollment 資料群組所提供之新可用資料元素的高階摘要如下：
   • 計劃註冊（PG&E 需求回應計劃名稱/狀態和 CAISO 資訊）：
   • （帳單）帳戶地址
   • 服務協議狀態
   • （目前）服務費率
   • （目前） 維修電壓 （僅限電動）
   • 維修儀表編號（如有）
   • 儀錶類型
   • （目前）儀錶讀取週期
   • （當前）備用費率選項，如果現場產生指示器
   • （預設間隔使用時間） 持續時間 （長度單位為秒）
   • （已登記的 PG&E 需求回應）計劃名稱（如適用）
   • PG&E 無財務義務的註冊需求回應 （DR） 計劃最早終止日期
   • 無論財務義務為何，PG&E 登記需求回應 （DR） 計畫的最早終止日期
   • PG&E 需求回應 （DR） 計畫 （註冊） 狀態
   • PG&E 需求回應 （DR） 計劃註冊日期
   • PG&E 需量回應 （DR） 計劃取消註冊日期
   • 這些新資料元素的 Atom XML XSD （XML Schema Definition） 對應按照以下文件擷取：
     下載支援的資料元素 （PDF）
   • 關聯式資料階層模型概述如下：
     下載 PGE ESPI 資料模型 （PDF）
   • UsagePoint （亦稱 SA UUID）
     • ServiceDeliveryPoint\tariffProfile（目前的服務費率表 AKA 費率表，包括備用費率選項，如適用）
     • readCycle（目前儀錶讀取週期）使用摘要
     • readCycle（帳單服務週期）
     • 商品 （包括電子帳單電壓位準）
     • tariffProfile （計費服務費率，包括備用費率選項，如適用
   • 讀取類型
     • 商品（包括電氣的目前電壓位準和備用費率選項的首碼，如適用）
   • 客戶帳戶
     • （帳戶帳單地址）：
     • mainAddress/streetDetail...
     • 主要地址/城鎮詳細資料...
     • mainAddress/postalCode...
   • 客戶協議
     • 狀態\值 （SA 狀態
   • 需求回應計畫
     • 程式名稱
     • 註冊狀態
     • 程式日期/程式日期
     • 程式日期/程式日期說明
   • 電錶
     • 序號 （公尺 ID）
     • 類型 （公尺類型）
     • （目前） 間隔長度
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 概述如下：
     下載 XSD （ZIP）
     注意：XSD 向下相容。
   • 第三方將能夠變更其註冊，以便允許客戶在授權期間透過第三方入口網站選擇此資料群組，其管理註冊 >編輯 > 部分：指出您需要的客戶資訊，選取計劃註冊核取方塊。
   • 注意：這僅適用於新客戶授權。
     
   • 擷取 DR 註冊資訊的新 API 可在大量第三方層級以及個別客戶授權層級 （RetailCustomerID 層級） 上取得，概述如下：
     下載新的 PGE 支援 API （PDF）
   • 非同步 API，用於要求與第三方取得所有授權的 DR 註冊資訊
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailDRPrgInfo/{BulkID}
   • 用於在個別客戶授權層級要求 DR 註冊資訊的同步 API
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailDRPrgInfo/{RetailCustomerID}

請注意：除了客戶授權流程的變更外，其他變更也向下相容，且是第三方可選擇支援的自願增強功能。

如果您有任何疑問或需要額外支援，請隨時傳送電子郵件至 sharemydata@pge.com。

新功能：

1. 客戶現在可以從簡化的 Click-Through 授權程序中獲益。
   • 我們已更新客戶如何與貴公司分享資料的詳細資訊。
     瞭解客戶如何與公司分享資料
     
     注意： 這些變更，尤其是對授權 UI 的改進，已針對行動裝置（例如電話或平板電腦）進行最佳化。
   • 客戶可透過其 PG&E 線上帳戶存取的管理授權流程已變更：
     • 客戶仍然可以隨時從現有授權中移除 SAID、延長授權結束日期和/或取消授權。但是，若要新增其他 SAID 和/或變更授權資料元素，需要取消現有授權，並建立新的授權。
2. 如有需要，第三方現在可以使用此 API 透過 DELETE 作業來撤銷使用其第三方用戶端存取權杖 （在初始 SMD 第三方註冊程序中提供） 的個別客戶授權：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID}
   
   註釋 1：對於 PG&E 的實施， AuthorizationID 參數與 SubscriptionID 的值相同。
   
   附註 2：新的 API 讓第三方能夠撤銷（取消）授權。但是，只有客戶本身可以透過 SMD 管理授權頁面移除 SA ID 和/或更新授權結束日期。
   
   提醒：如同所有 API 資料要求，第三方必須先使用其最新的重新整理金鑰來要求新的金鑰配對（用戶端存取 + 重新整理金鑰）。
   
   動態密碼卡過期期提醒：
   • 存取金鑰：1 小時
   • 用戶端存取金鑰：5 分鐘
   • 對應的重新整理權杖：1Yr
3. 如有需要，第三方現在可以使用相同的公司名稱和稅務 ID 建立多個共用我的資料 （SMD） 註冊。但是，顯示名稱 （客戶在授權時看到的名稱） 仍需要唯一。
   
   注意：以上所有變更皆向下相容，且為第三方可選擇支援的自願增強功能。下載此版本的支援文件：
   
   支援_APIS.SMD_CLICK-THRU_1.0 （PDF）
   
   SUPPORT_DATA_ELEMENTS_RETAILCUSTOMER.SMD_CLICK_THRU_1.0 （PDF）
   
   PGE_ESPI_DATA_MODEL.SMD_CLICK-THRU_1.0 （PDF）
   
   支援_資料_元素_ESPIDERIVED.SMD_CLICK_THRU_1.0 （PDF）
   
   ESPI_XSDS （ZIP）

2015 年 12 月 20 日

必要變更：以下 SMD 2.0 更新要求變更第三方。

1. 考慮到多個公用程式中除了 PG&E 之外，有 GBCMD（綠色按鈕連線我的資料）實作的第三方，我們將在 OAuth 授權序列期間，將重新導向中的資料CustodianID（即 dataCustodianID=PGE）傳回至 ThirdPartyScopeSelectionScreenURI。
2. 接受日期參數的 API 要求 （例如，批次要求），必須使用 Zulu 資料參數 （例如，已發佈-max/已發佈-min）。不支援 API 要求中日期參數的其他日期格式。
   • 接受日期參數的 API 會依照附件的支援 APIs.xlsx 進行記錄
3. 間隔計量電力使用資料中包含的間隔 TOU 指示器 （如適用，每個間隔的 TOU 週期對應）
   • 請參考固定的計劃 ID 對應，詳細說明每個間隔 TOU 列舉的對應內容（例如，1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）
4. 在資料中找到的 client_idCustodianScopeSelectionScreenURI （用於第三方發起的 OAuth），以及在註冊測試期間的應用程式資訊資源第三方要求中提供的客戶_id，如果尚未更新為 5 位數 （例如新增前導零等）。此外，URL 結尾不再包含 '&verified=true'。第三方將需要相應更新其 URL。
   • 為詳細說明，資料CustodianScopeSelectionScreenURI 如下所示：https://sharemydataqa.pge.com/myAuthorization/?clientId=XXXX （XXXX 為 clientID）
   • 因此，目前的客戶 ID 為 123 將變更為 00123 之類的資料，代表他們的新資料CustodianScopeSelectionScreenURI 如下：
     https://sharemydataqa.pge.com/myAuthorization/?clientId=00123 （舊網址如下：https://sharemydataqa.pge.com/myAuthorization/?clientId=00123&verified=true）
5. 註冊為“ESP”或“能源服務提供商”的第三方將更改為標準用戶類型。功能上沒有變更，僅在使用者類型標題中。區分 ESP 使用者類型 （與標準使用者類型不同） 是不必要的區分，在註冊過程中，在未提供任何差異化功能的情況下，會造成混淆，因此已淘汰。

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 第三方將能夠自動變更/更新其最初在註冊期間提供的 SSL 憑證（例如，憑證即將到期時），透過管理註冊 >編輯 > 新章節中的第三方入口網站進行：SSL 憑證資訊 （更新選項）。
2. 第三方可註冊以接收授權的基本帳單資訊、客戶資訊及氣體資料。  間隔計量和非間隔計量客戶均有資格授權共享 SMD 2.0 的資料。新可用資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
     • 注意：對於授權的非間隔計量客戶，第三方將只會收到帳單使用量總計 （即使用量摘要中），且無間隔使用量讀取 （例如，因無法使用時每小時/每天讀取）
   • 客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、帳戶 ID、服務合約 ID、服務合約服務開始日期、
   • 間隔氣體使用資料：（僅限間隔計量氣體 SA）
     • 間隔（即每天）氣體讀數
   • 新資料元素會依照附件，支援的資料元素.xlsx 進行繪製
   • 隨附之 PGE ESPI Data Model.xlsx 中概述了關聯式資料階層
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。注意：XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）

如果您有任何疑問或需要其他支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 12 月 18 日
 

必要變更：以下 SMD 2.0 更新要求變更存取自身資料的部分使用者：

1. 接受日期參數的 API 要求 （例如，批次要求），必須使用 Zulu 資料參數 （例如，已發佈-max/已發佈-min）。不支援 API 要求中日期參數的其他日期格式。
   • 接受日期參數的 API 會依照附件的支援 APIs.xlsx 進行記錄
2. 間隔使用時間 （TOU） 指標包含於間隔計量電力使用資料中 （如適用，指示每個間隔的 TOU 週期對應）
   • 請參考固定的計劃 ID 對應，詳細說明每個間隔 TOU 列舉的對應內容（例如，1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 自我存取使用者將能夠自動變更/更新其最初在註冊期間提供的 SSL 憑證（例如憑證即將到期時），透過管理註冊 > 編輯 > 新區段的第三方入口網站進行：SSL 憑證資訊 （更新選項）
2. 自我存取使用者註冊將更新，以包含授權的基本帳單資訊、客戶資訊及氣體資料。與非間隔計量服務協議一併計量的間隔，均有資格取得 SMD 2.0 的 （自我） 授權。新可用資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
     • 注意：對於授權的非間隔計量客戶，第三方將只會收到帳單使用量總計 （即使用量摘要中），且無間隔使用量讀取 （例如，因無法使用時每小時/每天讀取）
   • 客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、帳戶 ID、服務合約 ID、服務合約服務開始日期、
   • 間隔氣體使用資料：（僅限間隔計量氣體 SA）
     • 間隔（即每天）氣體讀數
   • 新資料元素會依照附件，支援的資料元素.xlsx 進行繪製
   • 隨附之 PGE ESPI Data Model.xlsx 中概述了關聯式資料階層
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。注意：XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）

如果您有任何疑問或需要其他支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 12 月 18 日
 

必要變更：以下 SMD 2.0 更新要求變更 CCA 實施的一部分。

1. 必須使用 Zulu 時間日期參數提出特別要求 （例如：歷史資料）。不支援 API 要求中日期參數的其他日期格式。
2. 每日大量使用摘要將開始包含基本帳單資訊，而每日大量客戶摘要將包含其他客戶資訊。此新資料將提供給目前接收資料的間隔計量客戶，以及目前未接收資料的區域內非間隔計量客戶。最後，每日大量使用摘要中提供的間隔使用值將包括適用的間隔 TOU 指標。新資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
   • （其他）客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、服務協議服務開始日期、帳戶 ID
   • 間隔計量電力使用資料中包含的間隔 TOU 指示器 （如適用，每個間隔的 TOU 週期對應）
     • 請參考固定的計劃 ID 對應，詳細說明每個間隔 TOU 列舉的對應內容（例如，1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。請注意，XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）
   • 新資料元素會依照附件，支援的資料元素.xlsx 進行繪製
   • 隨附之 PGE ESPI Data Model.xlsx 中概述了關聯式資料階層

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 除了收到的每日通知外，CCA 還可以在下列位置臨時要求客戶資訊：https://api.pge.com/GreenButtonConnect/espi/1_1/Batch/BulkRetailCustomerInfo/{BulkID}（在要求時返回客戶資訊的最新快照）。
2. CCA 在管理註冊 > 編輯 > 新區段下，將能夠透過第三方入口網站自動變更最初在註冊期間提供的 SSL 憑證 （例如，憑證即將到期時）：SSL 憑證資訊 （更新選項）

如果您有任何疑問或需要其他支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 8 月 21 日
 

新功能：

1. Oauth 回應中的狀態參數和資源 URI 變更
   • 作為 OAuth 授權碼請求的一部分，第三方可以選擇傳送狀態參數，讓 PG&E 將傳送該參數回給第三方。PG&E 也會在成功完成授權時傳送授權代碼。此可選狀態參數可用於協助第三方識別請求發起的位置，並將請求與其發起的授權相關聯。
   • 作為成功完成金鑰要求的一部分，我們會將 resourceURI 和 authorizationURI 與金鑰資訊分開分享。目前這些 URI 已翻轉，作為此版本的一部分，我們將更正它。

固定瑕疵：

1. 預設發佈日期-最大和發佈日期-最小
   目前 PG&E 要求第三方在 Epoch 秒內以公佈的最小值和公佈的最大值參數傳送每個資料請求，告訴 PG&E 他們請求資料的持續時間。我們正在實施一項變更，以處理下列情境的要求：
   • 發佈-最小值和發佈-最大值缺失
   • 已發佈的最小值和已發佈的最大值以 UTC 為單位
   • 發佈的最小值和發佈的最大值以 epoch 秒為單位
   如果參數缺失，PG&E 將返回預設日期，而不是在此變更之前返回的錯誤訊息。在我們的案例中，預設是日期 T-2 的一天資料。如果參數存在且格式正確，我們將繼續尊重參數。
2. 修復授權 xml 中的日期
   我們目前在 xml 授權中分享了發佈日期和授權日期。這些日期以毫秒為單位，而非以秒為單位，即標準。我們正在修復它，以便在 epoch 秒內傳回，而不是毫秒。
3. 針對 /resource/Subscription/{id}/UsagePoint/{id}/MeterReading/{id}/IntervalBlock 傳回不正確的 XML
   目前，我們針對上述資源層級 GET 傳回不正確的回應，其中 XML 的結構不正確，而且每個間隔重複輸入，而不是在 24 小時內建立一個單一間隔區塊。
   
   此為固定間隔，24 個間隔區塊只會傳回單一間隔區塊。

問題或疑慮？ 請聯絡ShareMyData@pge.com。

• 客戶授權您透過 My Energy 和他們的 PG&E 線上帳戶存取其資料。如需客戶如何授權第三方或其他實體存取其資料的詳細概觀，請檢視共用我的資料第三方概觀。

前往授權詳細資料

• 目前沒有限制。

• 客戶可以選擇特定的時間量，以便存取其資料，或者讓授權期間保持開放。
• 您的應用程式可以透過呼叫授權資源 API（例如.../espi/1_1/resource/Authorization 和/或.../espi/1_1/resource/Authorization/{AuthorizationID}）來檢查客戶授權的結束日期和其他授權詳細資料。
• 或者，您也可以登入您的帳戶並選擇管理授權，手動檢查授權結束日期。

• 如果客戶選擇定義的授權期間，則其授權將在該期間結束時到期。如果他們取消授權，則他們的授權將在他們取消授權後的隔天到期。
• 如果客戶選擇無限期作為其授權期間，則其授權不會過期。請注意，考量到第 24 條要求回應提供者及其他使用共用我的資料之程式，先前授權之日期範圍的事後修正，得於授權屆滿後提供至多三年予第三方。
• 請參閱"將如何處理資料更正？" 以取得關於接收更正的進一步詳細資料。

• 任何 PG&E 客戶若目前擁有天然氣或電力服務的有效服務 ID，都可以授權您使用新的 Share My Data 工具來存取其資料。

• 非常鼓勵有興趣透過 Share My Data 計畫參與分享資料的客戶註冊 My Energy 帳戶。這將使整個流程更有效率，也使他們能夠線上管理授權。
• 客戶可以在授權過程中註冊 My Energy 帳戶。
• 客戶可以手動取得線上共用我的資料授權表單，並透過電子郵件提交填妥的表單。
• 有關手動流程的更多資訊，請透過 ShareMyData@pge.com 與我們聯絡。

• 客戶必須透過其 PG&E 線上帳戶進行線上授權。但是，如果他們填寫並簽署共享我的資料授權書，則您可以代表他們提交給 PG&E。

下載共用我的資料客戶授權或撤銷授權表單 （PDF， 308 KB）

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並更新 OAuth 2.0 資訊區段下的欄位來更新您的 OAuth URI。

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並更新資料存取資訊區段下的欄位來更新您的通知 URI。

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並在 SSL 憑證資訊部分選擇 "更新" 來更新您的 SSL 憑證。請注意，上傳新憑證可能需要幾天的時間，才能使用新憑證更新 PG&E 系統。 
• 套用新憑證後，將傳送來自共用我的資料支援團隊的確認電子郵件。

• 收到表明您的註冊已被接受的電子郵件後，您將能夠登入您的 Share My Data 帳戶，並透過下載 PG&E SSL 憑證頁面下載我們的 SSL 憑證。

登入以分享我的資料

• 分享我的資料遵循綠色按鈕連接我的資料實施協議。Share My Data 也採用 OAuth 2.0 進行授權、傳輸層安全性 （TLS） 1.2 以及 NIST（國家標準與技術研究所）核准的最小網路安全通訊協定套件，因此不會交換任何明確的資訊。

• 保護客戶資訊是 PG&E 的首要任務。 PG&E 會依據所有法律和法規要求，包括加州公共事業委員會和其他單位所建立的要求，將有關其客戶的資訊，包括個人資訊視為機密。 
• 二十多年來，PG&E 和加州其他投資者擁有的公用事業一直受到非常嚴格的 CPUC 法規的約束，禁止他們在未經客戶明確同意的情況下向第三方披露特定客戶的資訊，例如帳單資料。 
• 一旦客戶授權釋出資料，客戶和第三方有責任保護這些資料。
• 客戶可以登入其 PG&E 線上帳戶並取消授權，隨時選擇停止與第三方分享資料。PG&E 的完整隱私政策和存取、收集、儲存、使用和披露能源使用資訊通知可在 pge.com/privacy 上找到。

• 在共用我的資料計畫的範圍內，第三方必須遵守共用我的資料平台條款與條件中指定的客戶資料隱私和保護規則，以及客戶資料存取費率中包含的要求。
• 第三方亦須遵守與保護客戶隱私相關的所有其他適用法律和法規，包括但不限於 CPUC 採用的能源使用資料隱私和安全保護規則，如決策 11-07-056（電子）的附件 D，也概述於 PG&E 的電氣規則第 27 條和加州民法第 1798.80 – 1798.84 節。
• 如需更多資訊，請選擇以下連結：
  分享我的資料條款與條件（PDF，190 KB）
  電工規則第 27 條 （PDF， 1.6 MB）
  決策 11-07-056 附件 D （PDF）
  尋找更多資訊：加州民法典第 1798.80 – 1798.84 節

• 請參閱以下連結，以取得所支援資料元素的詳細清單。

取得更多關於資料存取的資訊

• 有時候，由於我們的上游資料驗證程序發現有遺漏或不正確的資料讀取可能需要進一步處理（編輯和/或估計），因此缺少間隔使用資料。
• 對於週期性計費客戶 （例如有使用時間計費考量的客戶），這些執行個體會及時修正，以確保其即將到來的每月帳單上能準確計算帳單。

• 如果您想接收資料更正，請確保您在註冊時勾選通知我為就緒資料核取方塊，或登入您的線上帳戶並勾選編輯設定檔下的此核取方塊。然後，針對您獲授權存取的任何資料，我們將納入我們系統在過去 24 小時內擷取的資料更正，作為每日使用摘要的一部分。
• 資料更正將涵蓋授權期間的任何變更，最長三年。

註：考量到第 24 條要求回應提供者及其他使用共用我的資料之程式，先前授權日期範圍之事後更正，得於授權屆滿後最長三年內提供給第三方。

• 如適用，PG&E 將發送通知至您在註冊時提供的通知 URL。通知包含對應於已預先包裝資料的 URL，供您返回，並使用提供的 URL 提出要求。資料已預先封裝，並在以下兩種情況下發送通知：（1） 您已在註冊檔案中選擇“資料已就緒時通知我”，在這種情況下，我們將把最新的每日資料與過去日期的任何更正進行封裝，或者（2）您提前提出了一個臨時非同步請求，請求的資料現已準備就緒。情境 1 說明於 "DATA ACCESS：資料存取頁面上的資料存取方法圖表和情境 2 的每日訂閱部分如資料存取：AD HOC REQUEST （ASYNCHRONOUS）" 部分也位於資料存取頁面。

以上就診資料存取

• Share My Data 提供的電力使用資料並非加州獨立系統操作員 （CAISO） 指定的結算品質儀資料 （SQMD）。SQMD 的產生方式是將營收品質計資料 （RQMD） 乘以適用於該客戶的該間隔電壓位準的分配損失係數 （DLF），將計量間隔轉換為 CAISO 所需的間隔期間，然後將每個間隔的結果加總至 CAISO 所需的彙總位準。
  
• PG&E 正在實施 ESPI 標準提供的 "QualityOfReading" （QOR） 類型的旗標，以傳達資料是否為營收品質。QOR 類型為使用資料擷取不同的可能品質值，包括“營收品質計資料”或“RQMD”的明確值。PG&E 將在資料傳輸中使用此 QOR 類型，如下所示：
  • PG&E 支援 ESPI 提供的 "UsageSummary" 類別，該類別將用於識別服務協議的計費日期、計費使用金額，以及要求時的使用資料品質。一旦帳單可用於要求的資料，便會填入使用摘要，並包含兩個 QOR 類型的旗標（元素）：
    • UsageSummary.QualityOfReading 元素 （在 UsageSummary 層級） 指出在要求時提供的最新間隔使用值加上對應於 UsageSummary.billing 期間日期的更正的品質。
    • 表示總計費使用量品質的 OverallConsumptionLastPeriod （作為 UsageSummary.OverallConsumptionLastPeriod.ReadingTypeRef 的一部分） 預設品質元素。
  • PG&E 也會使用 IntervalReading.ReadingQuality.Quality 元素，在要求時的間隔層級傳達使用資料的品質。

• 在註冊期間，您可以在“需要多少歷史資料”下拉選單中選擇您需要多少歷史資料，可以是24、36或48個月。
• 作為客戶授權允許您存取其資料的一部分，授權歷史期間將預設為授權中所包含的服務 ID（使用點）的註冊選擇。
• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並從標記為“需要多少歷史資料”的下拉選單中選擇來更新您請求的歷史資料。
• 請注意，歷史請求中提供的資料將從客戶授權的日期開始，而不是您向 API 請求的日期。

注意：您要求的歷史資料變更僅影響新客戶授權，而先前的客戶授權將反映您在授權時的選擇。

• 根據 ESPI 標準，該回應使用 Atom Publishing Standard。請選擇以下連結，以查看支援 API 的完整清單，以及可用資料元素。

取得更多關於資料存取的資訊

• 由 PG&E 安裝和讀取的有效電力和天然氣服務 ID 有資格透過 Share My Data 平台取得授權。
• 如果由於以下原因之一，與授權相關的服務 ID 發生了變更，則授權將轉移到新的服務 ID，並且將繼續存取歷史間隔使用資料：
  • 因未付款而暫時關閉
  • 移至間隔計費
  • 更換血糖機
  • 費率變更
• 導致服務 ID 變更的其他情況，例如移動地點或公司變更，將終止存取。此外，如果某個帳戶與您的 My Energy 帳戶取消連結，則所有透過共用我的資料授權的基礎服務 ID 都將因此遭到未授權。

• 若要判斷授權間隔資料的精細度，請參考 ESPI 標準提供的間隔長度元素。
• PG&E 以與計費目的收集的間隔使用資料相同的精細度提供間隔使用資料，一般是以每小時或 15 分鐘為基準，而對於具有間隔儀表的客戶，則為每天提供瓦斯資料。雖然電間隔儀的使用率會因客戶而異，但對於大多數住宅客戶，電間隔儀的使用率通常為每小時，對於大多數商業客戶，電間隔儀的使用率為 15 分鐘，而對於大多數客戶，氣間隔儀的使用率通常為每天。
• 對於非間隔儀表，將在可用時提供資料。

• 對於已安裝智慧電錶的大多數 PG&E 客戶而言，電力和瓦斯間隔使用資料可在次日結束前透過 Share My Data 平台取得。
• 已安裝電線載波 MV90 公尺的 PG&E 電力客戶中，有一小部分可能需要額外的時間才能取得資料。

• 雖然我們無法直接支援您的 API 設定，但我們確實有許多資源可供協助您的 IT 和技術資源進行開發過程。請參閱我們的 API 文件頁面以瞭解更多資訊。如有任何其他問題，請隨時聯絡ShareMyData@pge.com。

如需更多資訊，請造訪應用程式開發介面 （API）