Akıllı ev işlemlerinin nasıl geliştirileceğini öğrenmek için yeni adres olan Google Home Geliştirici Merkezi'ne hoş geldiniz. Not: Actions Console'da işlem oluşturmaya devam edersiniz.

Yerel sipariş karşılama uygulamasını kullanma

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Yerel sipariş karşılamayı desteklemek için aşağıdaki akıllı ev amaçlarına yönelik bir uygulama oluşturmanız gerekir:

  • IDENTIFY: Yerel olarak kontrol edilebilen akıllı cihazların bulunmasını destekler. Amaç işleyici, akıllı cihazınızın keşif sırasında döndürdüğü verileri ayıklar ve Google'a yanıt olarak gönderir.
  • EXECUTE: Komutların yürütülmesini destekler.
  • QUERY: Cihaz durumunu sorgulamayı destekler.
  • REACHABLE_DEVICES: (İsteğe bağlı) Bir merkezi (veya köprü) cihazın arkasında bulunan ve yerel olarak kontrol edilen bitiş cihazlarının bulunmasını destekler.

Bu uygulama kullanıcının Google Home veya Google Nest cihazlarında çalışır ve akıllı cihazınızı Asistan'a bağlar. Uygulamayı TypeScript (tercih edilen) veya JavaScript kullanarak oluşturabilirsiniz.

TypeScript, uygulamanızın döndürdüğü verilerin platformun beklediği türlerle eşleştiğinden emin olmak için bağlamalardan yararlandığından önerilir.

API hakkında daha fazla bilgi için Local Home SDK API referansı sayfasına bakın.

Aşağıdaki snippet'lerde yerel sipariş karşılama uygulamasını nasıl başlatabileceğinizi ve işleyicilerinizi nasıl ekleyeceğinizi görebilirsiniz.

Bağımsız
import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });
Merkez
import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onReachableDevices(reachableDevicesHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

Projenizi oluşturun

Yerel sipariş karşılama uygulamanızı dağıtmak üzere kodunuz ve tüm bağımlıları için bir JavaScript paketi oluşturmanız gerekir.

Tercih ettiğiniz paketleyici yapılandırmasıyla uygun proje yapısını önyüklemek için yerel sipariş karşılama uygulaması projesini başlatan kullanıcıyı kullanın.

Proje şablonları

Paketleyici yapılandırmanızı seçmek için npm init komutunu aşağıdaki örneklerde gösterildiği gibi çalıştırın:

Yok

Paketleyici yapılandırması olmayan TypeScript:

npm init @google/local-home-app project-directory/ --bundler none

Proje yapısı:

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

project-directory yerine yerel sipariş karşılama projesini içeren yeni bir dizin girin.

Web paketi

webpack paketleyici yapılandırması olan TypeScript:

npm init @google/local-home-app project-directory/ --bundler webpack

Proje yapısı:

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── webpack.config.web.js
├── webpack.config.node.js
└── serve.js

project-directory yerine yerel sipariş karşılama projesini içeren yeni bir dizin girin.

Toplayıcı

Rollup paket yapılandırması olan TypeScript:

npm init @google/local-home-app project-directory/ --bundler rollup

Proje yapısı:

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── rollup.config.js
└── serve.js

project-directory yerine yerel sipariş karşılama projesini içeren yeni bir dizin girin.

Parsel

Parcel paket yapılandırmasıyla TypeScript:

npm init @google/local-home-app project-directory/ --bundler parcel

Proje yapısı:

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

project-directory yerine yerel sipariş karşılama projesini içeren yeni bir dizin girin.

Proje düzeyinde genel görevleri gerçekleştirme

Oluşturulan proje aşağıdaki npm komut dosyalarını destekler:

Paket
cd project-directory/
npm run build

Bu komut dosyası, TypeScript kaynağını derler ve uygulamanızı dist/web alt dizinindeki Chrome çalışma zamanı ortamı, dist/node alt dizinindeki Node.js çalışma zamanı ortamına bağımlı olarak bir araya getirir.

Doğrula
cd project-directory/
npm run lint
npm run compile
npm test

Bu komut dosyası, TypeScript kodunuzun söz dizimini doğrular, dist/ alt dizininde herhangi bir çıkış oluşturmadan derler ve test.ts sitesinden otomatik testler çalıştırır.

Sunum
cd project-directory/
npm run start

Bu komut dosyası, geliştirme sırasında Chrome ve Node.js çalışma zamanı ortamları için uygulama paketlerinizi yerel olarak sunar.

IDENTIFY işleyicisini uygulama

Google Home veya Google Nest cihazı yeniden başlatıldığında ve doğrulanmamış yerel cihazlar (merkeze bağlı son cihazlar dahil) gösterildiğinde IDENTIFY işleyici tetiklenir. Yerel Ev platformu, daha önce belirttiğiniz tarama yapılandırma bilgilerini kullanarak yerel cihazları tarar ve IDENTIFY işleyicinizi tarama sonuçlarıyla birlikte çağırır.

Yerel Ev platformundaki IdentifyRequest, bir LocalIdentifiedDevice örneğinin tarama verilerini içerir. Cihazı keşfeden tarama yapılandırmasına bağlı olarak yalnızca bir device örneği doldurulur.

Tarama sonuçları cihazınızla eşleşiyorsa IDENTIFY işleyiciniz, akıllı ev meta verileri (türler, özellikler ve rapor durumu gibi) içeren bir device nesnesi içeren bir IdentifyResponsePayload nesnesi döndürmelidir.

Google, IDENTIFY yanıtındaki verificationId, SYNC yanıtı tarafından döndürülen otherDeviceIds değerlerinden biriyle eşleşirse cihaz ilişkilendirme oluşturur.

Örnek

Aşağıdaki snippet'lerde, bağımsız cihaz ve Hub entegrasyonları için sırasıyla IDENTIFY işleyicilerini nasıl oluşturabileceğiniz gösterilmektedir.

Bağımsız
const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const verificationId = "local-device-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: device.id || "",
          verificationId, // Must match otherDeviceIds in SYNC response
        },
      },
    };
    return response;
  };
Merkez
const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const proxyDeviceId = "local-hub-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: proxyDeviceId,
          isProxy: true,     // Device can control other local devices
          isLocalOnly: true, // Device not present in `SYNC` response
        },
      },
    };
    return response;
  };

Hub'ın arkasındaki cihazları tanımlama

Google bir merkez cihaz tanımlarsa bu merkezi, hub'ın bağlı son cihazları için bir kanal olarak değerlendirir ve bu son cihazları doğrulamaya çalışır.

Google'ın, bir hub cihazı olduğunu onaylamasını sağlamak üzere IDENTIFY işleyiciniz için aşağıdaki talimatları uygulayın:

  • SYNC yanıtınız nedeniyle kulübedeki yerel bitiş cihazlarının kimlikleri bildirilirse isProxy özelliğini trueIdentifyResponsePayload olarak ayarlayın.
  • SYNC yanıtınız hub cihazınızı raporlamazsa IdentifyResponsePayload içinde isLocalOnly özelliğini true olarak ayarlayın.
  • device.id alanı, hub cihazının yerel cihaz kimliğini içerir.

REACHABLE_DEVICES işleyicisini uygula (yalnızca merkezi entegrasyonlar)

REACHABLE_DEVICES amacı, hangi son cihazların yerel olarak kontrol edilebileceğini onaylamak için Google tarafından gönderilir. Google'ın keşif taraması yaptığı her sefer (yaklaşık olarak dakikada bir kez) bu amaç tetiklenir (merkezin çevrimiçi olduğu algılanırsa).

REACHABLE_DEVICES işleyicisini IDENTIFY işleyicisine benzer bir şekilde uygularsınız. Ancak işleyicinizin, yerel proxy (yani hub) cihazı tarafından erişilebilen ek cihaz kimlikleri toplaması gerekir. device.verificationId alanı, hub'a bağlı bir son cihazın yerel cihaz kimliğini içerir.

Yerel Ev platformundaki ReachableDevicesRequest, LocalIdentifiedDevice örneğini içerir. Bu örnek üzerinden hem tarama cihazı kimliğini hem de tarama sonuçlarından gelen verileri alabilirsiniz.

REACHABLE_DEVICES işleyiciniz, hub'ın kontrol ettiği son cihazları temsil eden verificationId değerlerini içeren bir devices nesnesi içeren ReachableDevicesPayload nesne döndürmelidir. verificationId değerleri, SYNC yanıtındaki otherDeviceIds ile eşleşmelidir.

Aşağıdaki snippet'te REACHABLE_DEVICES işleyicinizi nasıl oluşturabileceğiniz gösterilmektedir.

Merkez
const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest):
  IntentFlow.ReachableDevicesResponse => {

    // Reference to the local proxy device
    const proxyDeviceId = request.inputs[0].payload.device.id;

    // Gather additional device ids reachable by local proxy device
    // ...

    const reachableDevices = [
      // Each verificationId must match one of the otherDeviceIds
      // in the SYNC response
      { verificationId: "local-device-id-1" },
      { verificationId: "local-device-id-2" },
    ];

    // Return a response
    const response: IntentFlow.ReachableDevicesResponse = {
      intent: Intents.REACHABLE_DEVICES,
      requestId: request.requestId,
      payload: {
        devices: reachableDevices,
      },
    };
    return response;
  };

EXECUTE işleyicisini uygulama

Uygulamadaki EXECUTE işleyiciniz, kullanıcı komutlarını işler ve akıllı cihazlarınıza mevcut bir protokol üzerinden erişmek için Yerel Ev SDK'sını kullanır.

Yerel Ev platformu, bulut karşılama amacınız için EXECUTE ile aynı giriş yükünü EXECUTE işleyici işlevine iletir. Benzer şekilde, EXECUTE işleyiciniz çıkış verilerini EXECUTE amacının işlenmesiyle aynı biçimde döndürür. Yanıt oluşturma sürecini basitleştirmek için Yerel Ev SDK'sının sağladığı Execute.Response.Builder sınıfını kullanabilirsiniz.

Uygulamanızın, cihazın IP adresine doğrudan erişimi yok. Bunun yerine, şu protokollerden birini temel alan komutlar oluşturmak için CommandRequest arayüzünü kullanın: UDP, TCP veya HTTP. Komutları göndermek için deviceManager.send() işlevini çağırın.

Komutları cihazlara hedeflerken, cihazla iletişim kurmak için SYNC yanıtındaki cihaz kimliğini (ve varsa customData alanındaki parametreleri) kullanın.

Örnek

Aşağıdaki kod snippet'i, EXECUTE işleyicinizi nasıl oluşturacağınızı göstermektedir.

Bağımsız/Merkez
const executeHandler = (request: IntentFlow.ExecuteRequest):
  Promise<IntentFlow.ExecuteResponse> => {

    // Extract command(s) and device target(s) from request
    const command = request.inputs[0].payload.commands[0];
    const execution = command.execution[0];

    const response = new Execute.Response.Builder()
      .setRequestId(request.requestId);

    const result = command.devices.map((device) => {
      // Target id of the device provided in the SYNC response
      const deviceId = device.id;
      // Metadata for the device provided in the SYNC response
      // Use customData to provide additional required execution parameters
      const customData: any = device.customData;

      // Convert execution command into payload for local device
      let devicePayload: string;
      // ...

      // Construct a local device command over TCP
      const deviceCommand = new DataFlow.TcpRequestData();
      deviceCommand.requestId = request.requestId;
      deviceCommand.deviceId = deviceId;
      deviceCommand.data = devicePayload;
      deviceCommand.port = customData.port;
      deviceCommand.operation = Constants.TcpOperation.WRITE;

      // Send command to the local device
      return localHomeApp.getDeviceManager()
        .send(deviceCommand)
        .then((result) => {
          response.setSuccessState(result.deviceId, state);
        })
        .catch((err: IntentFlow.HandlerError) => {
          err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST;
          response.setErrorState(device.id, err.errorCode);
        });
    });

    // Respond once all commands complete
    return Promise.all(result)
      .then(() => response.build());
  };

QUERY işleyicisini uygulama

Uygulamadaki QUERY işleyiciniz, kullanıcı isteklerini işliyor ve akıllı cihazlarınızın durumunu bildirmek için Yerel Ev SDK'sını kullanıyor.

Yerel Ev platformu, buluta geçiş için sağlanan QUERY aracı ile aynı istek yükünü "QUERY" işleyici işlevine iletir. Benzer şekilde, QUERY işleyiciniz QUERY amacının işlenmesiyle aynı biçimde veriler döndürür.

Bir merkezin arkasındaki cihazlara komut gönderme

Bir merkezdeki son cihazları kontrol etmek amacıyla, merkezin komutun hangi cihaza yönelik olduğunu belirlemesi için merkeze gönderilen protokole özgü komut yükünde ek bilgi sağlamanız gerekebilir. Bazı durumlarda, bu doğrudan device.id değerinden çıkarılabilir. Ancak, bu mümkün olmadığında söz konusu ekstra verileri customData alanının bir parçası olarak eklemeniz gerekir.

Uygulamanızı TypeScript kullanarak oluşturduysanız uygulamanızı JavaScript'e derlemeyi unutmayın. Kodunuzu yazmak için tercih ettiğiniz modül sistemini kullanabilirsiniz. Hedefinizin Chrome tarayıcı tarafından desteklendiğinden emin olun.

Önceki
Cihaz keşfini destekleme
Sonraki
Test ve hata ayıklama